Skip to content

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 Logs

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 – by using TORO Integrate's own user interfaces!

These views display a live stream of TORO Integrate's application logs by making use of web socket connections that receive the log messages as they are published by TORO Integrate. However, to let TORO Integrate post the logs via web socket to the particular destination that these views listen to (/topic/logs2), 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

To view a particular TORO Integrate server's logs in Coder Studio:

  1. Right click the instance from the Coder Navigator and;
  2. Click Open Integrate Console.

Accessing the *Console* view

Ta-da! You now have the Console view visible in Coder Studio.

The *Console* view in Coder Studio

This view presents a couple of handy components that are intended to help you with inspecting the application's logs. Each component, shown in the following screenshot, is described below in order from left to right.

*Console* view actions

  • Terminate Button

    Terminates the web socket 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.

  • 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.

  • 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 Command while focused on the Console view.

    The *Find* dialog

To view a particular TORO Integrate server's logs in Coder Cloud:

  1. Right click in any empty space in the Coder Navigator view and;
  2. Click Open Integrate Console.

Accessing the *Console* view

Ta-da! You now have the Console view visible in Coder Cloud.

The *Console* view in Coder Cloud

This view presents a couple of handy components that are intended to help you with inspecting the application logs. Each component, shown in the following screenshot, is described below in order from top to bottom.

*Console* view actions

  • Word Wrap Button

    Wraps the log messages currently displayed in the Console view.

  • Clear Console Button

    Clears all log messages currently displayed in the Console view.

To go to the Application Logs page:

  1. Select Server Status from the main menu.
  2. Click on Application Logs from the sub-menu that'll pop out after doing Step #1.

The *Application Logs* menu item under the main menu

Ta-da! You are now in the Application Logs page!

The *Application Logs* page

This page presents a couple of handy components that are intended to help you with inspecting the application logs. Each component, highlighted in the following screenshot, is described below.

The *Application Logs* page tools

  • 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.

  • Download Button

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

  • Viewable Lines Input

    The maximum number of lines shown in the logs panel. The Application Logs page shows only the most recent n lines where n is the maximum viewable lines.

  • 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

    Displays the current time on the server.

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 prefer 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 allows you to add, edit, and delete a logger. But before you can do any of these actions, you must head to the application loggers view using the instructions below:

  1. Right click the target instance in the Coder Navigator view and;
  2. Click Configure Loggers from the 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.

Accessing configured application loggers

Head to the Application Logs page3 and select the Loggers tab. Inside the *Application Logs* page's *Loggers* tab

Adding Loggers

To add a new logger, follow the steps below:

  1. Click the plus icon on the right side of the Configure Loggers dialog.

    Configured application loggers

  2. Specify the name of the logger and select the log level you want for this logger.

    Adding a new application logger

  3. Click Ok.

  1. Click the plus icon on the upper right side of the Configure Loggers dialog.

    Configured application loggers

  2. Specify the name of the logger and select the log level you want for this logger.

    Adding a new application logger

  3. Click Ok.

  1. Click the Add button.
  2. Specify the name of the logger and select the log level you want for this logger.

    The new application logger form

  3. Click 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 you have published via the aforementioned class.

Editing Loggers

To reconfigure a logger, simply find its entry among the list of loggers. You may then re-specify the log level of that particular logger by re-selecting any of the options in its corresponding log level select box. You cannot, however, rename the logger.

Editing a logger in the *Configure Loggers* dialog

Editing a logger in the *Configure Loggers* dialog

Editing a logger in the *Application Logs* page

Deleting Loggers

To delete a logger:

  1. Select which loggers you want to delete. Holding Command while clicking on entries allows you to select multiple loggers.

    Selecting application loggers

  2. Click the delete button on the right side of the dialog.

  1. Select which loggers you want to delete.

    Selecting application loggers

  2. Click the delete button on the right side of the selected logger.

Find the logger you want to delete and click on the logger entry's corresponding Delete button. Deleting a configured 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 in 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.

Required Appenders

TORO Integrate also 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/logs2 over a web socket connection. The following components need this appender to function properly:

    • Coder Studio's Console view
    • Coder Cloud'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 in the Viewing Log Files 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 files1, 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. or in other words, existing log files excluding the current log file 

  2. /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. 

  3. Discussed in Viewing Console Logs, Server Admin UI.