Martini Services Analyzing Service Logs

Understanding and monitoring the behavior of Martini during runtime is crucial for efficient error handling and debugging. Martini facilitates this through comprehensive logging, leveraging the robust capabilities of the Apache Log4j framework. This section will guide you through accessing and customizing these logs to suit your debugging needs.

Application Logs

Martini records a wide range of events to aid in debugging and transaction tracing. These logs are powered by Apache Log4j, a leading logging framework in Java development. While Martini comes pre-configured with Apache Log4j for immediate logging capabilities, understanding and customizing its configuration can greatly enhance your ability to diagnose issues.

Familiarizing Yourself with Log4j

Before diving into log analysis, we recommend familiarizing yourself with Log4j's terminology and configuration options. Reading the Apache Log4j manual is an excellent start, providing a foundation for understanding the logging mechanism within Martini.

Accessing Log Files

Martini stores its logs in the logs directory, located within the application's home directory. These logs are accessible directly and are structured as follows:

<home>
...
├── conf
│   ├── ...
│   ├── log4j.properties
│   ├── ...
├── core
├── data
├── logs
│   ├── martini-log.txt
│   ├── martini-log.txt.2018-04-24
│   ├── martini-log.txt.2018-04-25
...

Logs are managed using a custom FileAppender configuration, which extends the functionality of the DailyRollingFileAppender. This setup ensures that log messages are saved to the local filesystem and rolled over daily. By default, the current log file is named martini-log.txt, with previous logs appended with their respective dates.

To configure the log output, you may edit the log4j.properties file located in the conf directory. An example configuration might look like this:

log4j.appender.file=io.toro.martini.core.util.MartiniFileLogger
log4j.appender.file.File=${application.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

This configuration snippet demonstrates how to set up a file-based logger, specifying the file path, naming pattern, and layout for log messages. Adjusting these settings allows you to tailor log management to meet your specific requirements, enhancing your ability to debug and trace application behavior effectively.

Viewing Log Messages

Martini offers intuitive interfaces for inspecting application logs, enabling developers to efficiently monitor and debug their applications. This section outlines the primary method for accessing these logs via the Martini IDE.

Logs View

Accessing application logs in Martini is straightforward with the Logs view. This feature provides a real-time glimpse into your application's operational status by displaying the most recent log messages.

How to Access the Logs View

To open the Logs view:

In the Navigator view, right-click on the Martini instance you wish to inspect.
Select "Open Martini Logs" from the context menu.

This action brings up the Logs view, presenting the latest log messages generated by your application.

The toolbar in the Logs view offers several controls to customize your log viewing experience:

View up to Textbox: This field allows you to specify the number of log lines to display, limiting the view to the most recent entries up to the number you set.
Ascending Checkbox: Ticking this box reverses the order of log display, showing the newest entries at the top. Unticking it reverts to the default behavior, where new logs appear at the bottom.
Word Wrap Button: Activating this feature wraps long log entries, preventing horizontal scrolling. This ensures that all log content is easily readable within the confines of the view.
Refresh Button: Clicking this button forces the Logs view to update. It's particularly useful after changing settings like the maximum number of displayed lines or the log order to ensure the view reflects your adjustments.
Download Button: This option enables you to download a copy of the logs from a specific date, providing a convenient way to save and share log data for further analysis.

Console View

The Console view is an essential tool within Martini for monitoring application logs in real-time. It provides instant insights into the operational behavior of your applications, facilitating quick debugging and analysis.

Overview

Unlike other views that may require manual refreshes to display new log entries, the Console view streams log messages directly as they occur. For embedded local instances, this view is automatically opened during startup and can display logs from earlier sessions.

Important Configuration

To enable the real-time streaming of log messages, Martini relies on a WebSocket connection facilitated by the StompOverWebSocketPublishingAppender. This appender is crucial for transmitting log data to the Console view.

Ensure the following configuration is present in your log4j.properties file to enable this functionality:

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

By default, Martini is configured with this appender, allowing seamless log streaming to the Console view.

The toolbar in the Console view offers a range of controls for managing the log stream and viewing different types of outputs:

Terminate Button: Ends the WebSocket connection, stopping the stream of new log messages to the Console view.
Remove Launch Button: Closes the Console view for a specific instance.
Remove All Terminated Launches Button: Closes Console views for all instances that have been terminated.
Show Logs Button: Returns the Console view to its default state, displaying server log messages.
Show Model Output Button: Displays the output of a previously executed service.
Show JSON Output Button: Shows the JSON string representation of the service output.
Show XML Output Button: Shows the XML string representation of the service output.
Collapse All Button: Collapses all models in the Output model tree, hiding their properties.
Expand All Button: Expands all models in the Output model tree, making all properties visible.
Clear Console Button: Clears the Console view of all current log messages.
Word Wrap Button: Wraps text to fit within the Console view, eliminating the need for horizontal scrolling.
Scroll Lock Button: Freezes the Console view, preventing it from auto-scrolling to the most recent log messages.
Show Console When Output Changes Button: Automatically brings the Console view to the forefront when new output is detected.
Pin Console Button: Keeps the Console view visible, regardless of other opened views.
Display Selected Console Button: Focuses on a specific Console view among multiple opened consoles.
Open Console Button: Launches a new Console view.
Find Dialog: Allows for searching specific log messages within the Console view. Activated with mod+F.

Application Logs Page

For users with a Martini Runtime subscription, the Martini Runtime Admin web interface provides a comprehensive tool for viewing log messages. This feature enhances the ability to monitor application behavior directly through a web interface.

Accessing Application Logs

To access the Application Logs page:

Navigate using the menu on the left-hand side of the Martini Runtime Admin interface.
Go to Server Status > Application Logs.

This page is equipped with a toolbar that includes several functionalities to assist in log management.

The toolbar on the Application Logs page contains the following controls:

View Up To Textbox: Allows you to specify the maximum number of log lines to display, limiting the view to the most recent entries up to the number you configure.
Ascending Checkbox: When enabled, the logs are displayed with the most recent entries at the top. If unchecked, the newest logs appear at the bottom of the panel.
Load Button: Performs a full refresh of the log display. This is necessary after adjusting settings like the maximum number of lines or the sort order of the logs.
Server Time Label: Shows the current server time, providing context for the timing of log entries.
Download Button: Enables the downloading of logs for a specific date, facilitating offline analysis and archiving.

CLI Tool for Log Management

Martini also offers a CLI tool for querying server logs, adding flexibility in how you access log data.

System Commands

head: Displays the beginning portion of a log file for a specified date.
logs: Downloads log files for a specified date up to the present moment.
tail: Shows the end portion of a log file for a specified date.

Configuring the Logging Service

Martini's logging service can be configured in two primary ways: through the user interface for basic adjustments or by directly editing the log4j.properties file for comprehensive customization.

Via the UI

Configuring loggers via the UI is straightforward and covers basic needs such as adjusting log levels and defining loggers. To access the logger configuration interface:

In the Navigator view, right-click on the instance you wish to configure.
Select "Configure Loggers" from the context menu.

This approach is recommended for quick and simple modifications.

Advanced Configuration

For more detailed customization, editing the log4j.properties file allows full access to Log4j's extensive configuration options. This method is advisable for advanced configurations that go beyond the scope of the UI's capabilities.

Accessing Configured Application Loggers

To view or modify configured loggers:

Navigate to the Loggers tab within the Application Logs page. This area provides an overview of all configured loggers and their current settings, allowing for fine-tuned control over the logging behavior of your Martini instance.

Managing Loggers in Martini

Martini provides flexible options for adding, editing, and deleting loggers, as well as configuring log storage and retrieval. This section covers these capabilities in detail.

Adding Loggers

To introduce a new logger to your Martini instance:

Navigate to the appropriate interface and click the "Add" button.
In the dialog that appears, enter the name of the new logger and select its log level.
Confirm by clicking "OK," "Create," or "Save."

Naming Loggers

A best practice for naming loggers is to use class names. This approach facilitates the identification of log message origins. Martini itself follows this convention, with a key logger named "Martini" for class-specific logging.

Editing Loggers

To adjust a logger's settings:

Locate the logger in the list.
Use the dropdown next to the logger to change its log level.

Note: Renaming a logger is not supported.

Deleting Loggers

To remove a logger:

Select the desired logger from the list.
Click the "Delete" button.

Advanced Configuration via log4j.properties

For more complex logging requirements, direct modification of the log4j.properties file is necessary. This file is located in the Martini's conf directory. Before making changes, familiarize yourself with Apache Log4j to understand the implications of your configurations.

Utilizing the REST API

Martini's REST API extends logging capabilities, enabling remote operations such as:

Retrieving a list of valid log levels.
Adding or removing loggers.
Accessing log files.

Required Appenders

Certain Martini components rely on specific appenders. These include:

StompOverWebSocketPublishingAppender: Essential for real-time log streaming to the Logs view, Console view, and the Application Logs page in the Martini Runtime Admin UI.
APIResponseLogAppender: Required for the debugger's functionality.

Backing Up Log Files

Martini employs a custom appender, similar to the DailyRollingFileAppender, for log file management. This appender supports automatic compression and deletion of old log files based on configuration settings in the log4j.properties file:

# Configures the maximum number of days to keep log files before deletion.
log4j.appender.file.MaxNumberOfDays=7
# Enables compression of log files prior to their deletion.
log4j.appender.file.CompressBackups=true

Customizing Log Message Destination

The default destination for log messages using the StompOverWebSocketPublishingAppender is /topic/logs. This can be customized in the log4j.properties file via the log4j.appender.stomp.destination property.