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.

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

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.

This view's toolbar is comprised of the following items (listed 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.

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

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/logs¹, 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:

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):

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

  

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

This page also has a toolbar, comprised of the following items (listed 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.

CLI tool

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

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:

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.

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.

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:

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.

Deleting loggers

In order to delete a 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.

Click the corresponding delete button of the 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/logs¹ 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:

# 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. ↩↩