Skip to content

Toro Cloud Dev Center


Application logs

Like many other applications, Martini 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, Martini uses one of the most popular logging frameworks in Java development: Apache Log4j. Out-of-the-box, Martini 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, it's highly recommend reading the Apache Log4j manual.

Viewing log files

Martini keeps all of its log files in the logs directory which is under the application's home directory. 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
│   └── martini-log.txt
│   └── martini-log.txt.2018-04-24
│   └── martini-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 martini-log.txt while the rolled-over log files are suffixed with their respective dates.

1
2
3
4
5
log4j.appender.file=io.toro.martini.core.util.MartiniFileLogger
log4j.appender.file.File=${toroesb.home}/logs/martini-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 log messages

Martini has several interfaces for viewing application logs.

Logs view

The simplest and most straightforward way to check application logs is through the Logs view. This view allows you to see the last n log messages produced by your instance. To open this view, right click on the chosen Martini instance in the Navigator view, then choose Open Martini Logs.

Logs view

Logs view

This view's toolbar is comprised of the following items (listed in order):

Logs view toolbar

Logs view toolbar

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

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

  • Download button

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

Console view

The Console view displays Martini's application logs in real time. In most cases, this view shows only the latest stream of logs; displaying only messages published by the instance from the moment the view was opened. However, for the embedded local instance (which opens the Console view during startup), this view may contain log messages published much earlier.

Console view

Console view

Must enable StompOverWebSocketPublishingAppender

Interfaces that display a live stream of Martini's application logs, like the Console view, make use of a WebSocket connection to fetch the logs from the server. They listen to a JMS destination, /topic/logs1, for the log messages and render them upon receipt.

However, for the server to post the logs via WebSocket to /topic/logs, you must have StompOverWebSocketPublishingAppender enabled in your log4j.properties file, which is how Martini is configured by default:

1
2
3
log4j.appender.stomp=io.toro.martini.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

This view's toolbar is comprised of the following items (listed in order):

Console view toolbar

  • Terminate button

    Terminates the WebSocket connection that receives Martini'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 XML 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.

  • Show console when output changes button

  • Pin console button button
  • Display selected console button
  • Open console button

  • Find dialog

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

    The Find dialog

Console view toolbar

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

  • Clear console button

    Clears all log messages currently displayed in the Console view.

Application Logs page

If you're on a Martini Runtime subscription, you can also view log messages from the Martini Runtime Admin web interface. To do this, use the menu on the left-hand side, and navigate to Server Status > Application Logs.

Application Logs page

This page also has a toolbar, comprised of the following items (listed in order):

Application Logs toolbar

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

CLI tool

The CLI tool also provides a way to query server logs. Under System Commands of the help section:

1
2
3
4
System Commands
        head: Prints the head of a log on a specified date
        logs: Download logs on a specified date, up to the present
        tail: Prints the tail of a log on a specified date

Configuring the logging service

You can configure Martini's logging service in two ways: (1) by setting the loggers in the 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. It's recommended using the user interface for quick edits but for advanced configuration and to fully benefit from Apache Log4j's features, it's suggested amending the log4j.properties file.

Via the UI

Loggers are responsible for capturing logging information and then passing them to the appropriate appenders. Martini Desktop, Martini Online, and the Martini Runtime 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 Navigator view; and
  2. Click Configure Loggers from the appearing context menu.

Accessing configured application loggers

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

Inside the Application Logs page's Loggers tab

  1. Head to the Application Logs page 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 add button.
  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, you can easily identify the origin of a log message. In fact, this is how Martini names its own loggers.

Logger's logger, however, is named Martini. 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 click the delete button on the right side of the dialog.

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

Deleting an application logger Click the corresponding Delete link 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 that 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. The log4j.properties file is located under Martini's conf directory.

Read the Apache Log4j manual first!

Again, a good understanding of Apache Log4j is recommended before you head on and adjust the default settings. It's advised to read the manual.

Via the REST API

Martini 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 Martini logs

Required appenders

Martini 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 Martini's log messages to subscribers of the endpoint /topic/logs1 over a web socket connection. The following components need this appender to function properly:

    • Martini's Logs view
    • Martini's Console view
    • Martini Runtime Admin UI's Application Logs page
  • APIResponseLogAppender

    Martini's debugger needs this appender to function properly.

Backing up log files

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

While both the MartiniFileLogger 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.