Skip to content

Home

Introduction

Development

Overview

IDEs

Services

Service manager

API Explorer

Application logs

Like many other applications, TORO Integrate logs certain events that have occurred while it's running. In many instances, you may find these logs useful for debugging and tracing transactions that have transpired.

Behind the scenes, TORO Integrate uses one of the most popular logging frameworks in Java development: Apache Log4j. Out-of-the-box, TORO Integrate already has Apache Log4j configured but if you wish to set it up yourself, there are plenty of ways on how to accomplish this.

Read the manual to familiarize yourself with Log4j

To accustom yourself with the terminologies and configuration options available in Log4j, we highly recommend reading the Apache Log4j manual.

Viewing log files

TORO Integrate keeps all of its log files in the logs directory which is right under the application's home folder. You can access the logs directly by opening these files.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<home>
...
├── conf
   └── ...
   └── log4j.properties
   └── ...
├── core
├── data
├── logs
   └── integrate-log.txt
   └── integrate-log.txt.2018-04-24
   └── integrate-log.txt.2018-04-25
├── packages
...

A customized FileAppender roughly based on the DailyRollingFileAppender is configured to persist the log messages to the local file system, rolling them over on a daily basis. With the default configuration, the most up-to-date log file is named integrate-log.txt while the rolled-over log files are suffixed with their respective dates.

1
2
3
4
5
log4j.appender.file=io.toro.integrate.core.util.IntegrateFileLogger
log4j.appender.file.File=${toroesb.home}/logs/integrate-log.txt
log4j.appender.file.DatePattern='.'yyyy-MM-dd
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{dd/MM/yy HH:mm:ss.SSS} %-5p [%c{1}] %m%n

Viewing console logs

It's possible to view the current stream of logs by watching the output of TORO Integrate's running process or at least, tailing the file it writes the logs to. But in this section, we're going to talk about accessing the logs in a more convenient manner – using TORO Integrate's user interfaces!

These views display a live stream of TORO Integrate's application logs using WebSocket connections that receive the log messages as they are published by TORO Integrate. However, to let TORO Integrate post the logs via WebSocket to the particular destination that these views listen to (/topic/logs1), you must have StompOverWebSocketPublishingAppender enabled in your log4j.properties file, like what we have by default:

1
2
3
log4j.appender.stomp=io.toro.integrate.logging.StompOverWebSocketPublishingAppender
log4j.appender.stomp.layout=org.apache.log4j.EnhancedPatternLayout
log4j.appender.stomp.layout.ConversionPattern=%d{dd/MM/yy HH:mm:ss.SSS} %-5p [%c{1}] %m%n%throwable

The Server Admin UI and both Coder applications provide an interface for viewing the server logs. Follow the steps below in order to access these spaces.

Viewing application logs

  1. Choose which instance whose logs you want to view and right click on it in the Coder Navigator view. This should produce a menu.
  2. Click Open Integrate Console or Open Integrate Logs. The former will trigger the Console view which is typically used when debugging, and only shows the latest server logs2. The latter will open the Logs view which is better for checking TORO Integrate's entire history of logs.

Viewing application logs

The Logs view is preferred if you want to see TORO Integrate's entire history of logs. To open this view:

  1. Right click on any blank space in the Coder Navigator view.
  2. Click Open Integrate Console.

The Console view also displays server logs but only shows the latest logs. It is preferred when checking the logs of services that are currently being debugged. If you want to use the Console view, just click on the Console tab at the bottom panel. This tab is present by default. If the bottom panel is not visible, expand it by clicking on the arrow button at the bottom of the window.

Button for showing the bottom panel

Viewing application logs

To view application logs, use the static navigation bar to go to Server Status > Application Logs.

Tools for Viewing Logs

From the screenshots above, you'll notice that every log viewer comes with a toolbar; the components that makeup these toolbars are intended to help you inspect application logs quicker and easier.

Logs view toolbar

Right under the Logs view's tab is its toolbar. It is comprised of the following components (in order):

  • View up to textbox

    The maximum number of lines shown in the Logs view. It shows only the most recent n lines where n is the configured maximum viewable lines.

  • Ascending checkbox

    When checked, allows you to view the most recent logs at the top of the logs panel; otherwise, shows the most recent logs at the bottom of the panel.

  • Reload logs button

    When clicked, performs a hard refresh of the view. If you have modified the maximum number of viewable lines or the order of the logs, you need to click this button to propagate the changes.

  • Download logs button

    Allows you to obtain a local copy of the logs printed on a specific date.

Console view toolbar

The Console view toolbar appears beside (or sometimes, underneath) the Console tab. It is comprised of the following components (in order):

  • Terminate button

    Terminates the WebSocket connection that receives TORO Integrate's published log messages. When this connection is terminated, the Console view will no longer receive new log messages.

  • Remove launch button

    Closes the Console view of a particular instance.

  • Remove all terminated launches button

    Closes all the Console views of instances that have already been terminated.

  • Show logs button

    Tells the Console view to go back to displaying server logs, which it does by default.

  • Show model output button

    Displays an interface for viewing the output of the now-terminated service which was run earlier.

  • Show JSON output button

    Displays the JSON string equivalent of the service output.

  • Show XML output button

    Displays the JSON string equivalent of the service output.

  • Collapse all button

    Used in conjunction with the Output model tree; it collapses all models so that all properties are hidden or, rather, nested within their parent models.

  • Expand all button

    Used in conjunction with the Output model tree; it expands all models so that all properties are visible.

  • Clear console button

    Clears all log messages currently displayed in the Console view.

  • Word wrap button

    Wraps the log messages currently displayed in the Console view so that you won't have to scroll sideways in order to view the entire log message.

  • Scroll lock button

    Allows you to stop the Console view from scrolling to the top or most recent log messages.

  • Find dialog

    Used for finding particular log messages. Triggered by pressing while focused on the Console view.

    The Find dialog

Logs view toolbar

Right under the Logs view's tab is its toolbar. It is comprised of the following components (in order):

  • View up to textbox

    The maximum number of lines shown in the Logs view. It shows only the most recent n lines where n is the configured maximum viewable lines.

  • Wrap text button

    Wraps the text displayed in the view so that log lines don't exceed the width of the view; logs are split into multiple lines so you don't have to scroll sideways in order to view them completely.

  • Refresh button

    When clicked, performs a hard refresh of the view. If you have modified the maximum number of viewable lines or the order of the logs, you need to click this button to propagate the changes.

  • Save logs button

    Allows you to obtain a local copy of the logs printed on a specific date.

Console view toolbar

The Console view toolbar appears underneath the Console tab. It is comprised of the following components (in order):

  • Wrap text button

    Wraps the text displayed in the view so that log lines don't exceed the width of the view; logs are split into multiple lines so you don't have to scroll sideways in order to view them completely.

  • Save logs button

    Allows you to obtain a local copy of the logs printed on a specific date.

  • Clear console button

    Clears all log messages currently displayed in the Console view.

Application Logs toolbar

The Application Logs page provides the following tools (in order):

  • View up to textbox

    The maximum number of lines shown in the Logs view. It shows only the most recent n lines where n is the configured maximum viewable lines.

  • Ascending checkbox

    When checked, allows you to view the most recent logs at the top of the logs panel; otherwise, shows the most recent logs at the bottom of the panel.

  • Load button

    When clicked, performs a hard refresh of the page. If you have modified the maximum number of viewable lines or the order of the logs, you need to click this button to propagate the changes.

  • Server time label

    Displays the current time on the server.

  • Download button

    Allows you to obtain a local copy of the logs printed on a specific date.

Configuring the logging service

You can configure TORO Integrate's logging service in two ways: (1) by setting the loggers in provided user interfaces or (2) by directly editing the log4j.properties file.

The former is simpler and limited to defining the loggers and their log levels while the latter gives you the whole nine yards – you can configure anything Log4j-related. We recommend using the user interface for quick edits but for advanced configurations and to fully benefit from Apache Log4j's features, we suggest amending the log4j.properties file.

Via the UI

Loggers are responsible for capturing logging information and then passing them to the appropriate appenders. Coder Studio, Coder Cloud, and the Server Admin UI allow you to add, edit, and delete a logger. But before you can do any of these actions, you must navigate to the interface for loggers using the instructions below:

Accessing configured application loggers

  1. Right click the instance whose loggers you want to configure in the Coder Navigator view; and
  2. Click Configure Loggers from the appearing context menu.

Accessing configured application loggers

  1. Right click on any empty space in the Coder Navigator view; and
  2. Click Configure Loggers from the context menu.

Alternatively, you can just click the Configure Loggers menu from the static menu at the left side of Coder Cloud.

Inside the Application Logs page's Loggers tab

  1. Head to the Application Logs page3 and;
  2. Go to the Loggers tab.

Adding loggers

To add a new logger, follow the steps below:

Adding a new logger

Adding a new logger

Adding a new logger

  1. Click the plus-iconed button (Add button in the Server Admin UI).
  2. In the appearing dialog, enter the name of your new logger and its log level.
  3. Click OK/Create/Save.

Naming loggers

One of the most common ways to name loggers is by naming them after classes. By doing so, we can easily identify the origin of a log message. In fact, this is how TORO Integrate names its own loggers.

LoggerMethods's logger, however, is named Integrate. You must have this logger present and enabled if you want to see the log messages published via the aforementioned class.

Editing loggers

To reconfigure a logger's log level, find its entry among the list of loggers. Click on the dropdown button to see the list of log levels and click to select the new log level of your logger. You cannot rename a logger.

Editing a logger

Editing a logger

Editing a logger

Deleting loggers

In order to delete a logger:

Deleting an application logger Select the logger you want to delete by clicking on it and then proceed to clicking the 'x'-iconed, delete button on the right side of the dialog.

Deleting an application logger Click the corresponding 'x'-iconed, delete button of the logger.

Deleting an application logger Click the corresponding Delete button of the logger.

Via the log4j.properties file

Sometimes, configuration options provided in the user interface will not be enough for your needs and it is in these moments you will need the flexibility and power of the log4j.properties file. To make changes to this file however, you need access to your server's local file system. log4j.properties is located under TORO Integrate's conf directory.

Read the Apache Log4j manual first!

Again, a good understanding of Apache Log4j is recommended before you head on and tweak the default settings. We advise reading the manual.

Via the REST API

TORO Integrate also provides REST endpoints for retrieving log files and maintaining loggers. This API allows you to remotely do things such as:

  • Get a list of allowable log levels
  • Add or remove loggers
  • Retrieve TORO Integrate logs

Required appenders

TORO Integrate has components that depend on certain pre-configured appenders. To avoid unexpected behavior, they must remain and be handled with care. These are the:

  • StompOverWebSocketPublishingAppender

    This publishes TORO Integrate's log messages to subscribers of the endpoint /topic/logs1 over a web socket connection. The following components need this appender to function properly:

    • Coder's Logs view
    • Coder's Console view
    • The Server Admin UI's Application Logs page
  • APIResponseLogAppender

    The following components need this appender to function properly:

    • Coder Studio's debugger
    • Coder Cloud's debugger

Backing up log files

As mentioned earlier section, TORO Integrate uses an appender loosely based on the DailyRollingFileAppender called the IntegrateFileLogger to write its log messages to files. With this appender, log files are backed up on a daily basis.

While both the IntegrateFileLogger and the DailyRollingFileAppender are capable of limiting the number of backup log files, what truly sets them apart is that unlike the latter that simply discards the files once a certain count has been reached, the former presents the option to compress the files before deleting them, given that it is configured to do so with the following properties:

1
2
3
4
5
# The maximum number of days before deleting the previous log files.
log4j.appender.file.MaxNumberOfDays=7
# Indicates whether the appender will archive all previous log files before 
# deleting them after the configured maximum number of days has been reached.
log4j.appender.file.CompressBackups=true

  1. /topic/logs is the default destination of the log messages received by StompOverWebSocketPublishingAppender but it can also be configured by log4j.properties's log4j.appender.stomp.destination property. 

  2. Logs received from the moment the view was opened. 

  3. Or in other words, existing log files excluding the current log file.