Log Swiftlet

Overview

The Log Swiftlet provides a central logging facility for the SwiftMQ router, handling the creation, rotation, and management of log files for informational, warning, and error messages. It supports configurable log file locations, size-based rotation, and retention of multiple generations of log files for auditing and troubleshooting purposes.

Features

Multi-Level Logging

The Log Swiftlet separates log output into three distinct levels: information, warning, and error. Each level can be independently enabled or disabled, and each writes to its own configurable log file. Log entries include a timestamp, the source (typically the swiftlet name), the log level, and the message content. This separation allows for fine-grained monitoring and filtering of log data according to severity.

Configurable Log File Names and Locations

The file paths for information, warning, and error logs are individually configurable. By default, logs are written to swiftmq_info.log, swiftmq_warning.log, and swiftmq_error.log in the working directory, but these can be changed to any writable location. The Log Swiftlet ensures that parent directories are created as needed.

Dynamic Enable/Disable of Log Levels

Each log level (information, warning, error) can be enabled or disabled at runtime via configuration. When a log level is disabled, messages of that level are not written to the corresponding log file. Disabling a log level also writes a configuration message to the log file to indicate the change.

Configuration Example:

<swiftlet name="sys$log" logfile-info-enabled="false" logfile-warning-enabled="true" logfile-error-enabled="true"/>

Log File Rotation and Retention

To prevent log files from growing indefinitely, the Log Swiftlet implements size-based log rotation. When a log file reaches the configured size limit (in kilobytes), it is rotated and a new file is started. A configurable number of old log file generations are retained for each log level, allowing for historical review and compliance with audit requirements. The rotation mechanism ensures that disk usage remains bounded while preserving recent log history.

Configurable Size Limit

The maximum size of each log file before rotation occurs is configurable via the size-limit property, specified in kilobytes. The default is 1024 KB (1 MB).

Configurable Number of Generations

The number of old log file generations to retain is controlled by the number-old-logfile-generations property. The default is 50, meaning up to 50 rotated log files are kept for each log level.

Configuration Example:

<swiftlet name="sys$log" size-limit="2048" number-old-logfile-generations="10"/>

Log Sink Facility

The Log Swiftlet provides a facility for creating additional log sinks, which are separate log files that can be used by other components or custom code. Each log sink is created in a configurable directory and uses the same rotation and retention policies as the main log files. This allows for modular logging and separation of concerns within the router.

Configurable Log Sink Directory

The directory where log sinks are created is configurable via the logsink-directory property. By default, log sinks are created in the current working directory, but this can be changed to any writable location.

Configuration Example:

<swiftlet name="sys$log" logsink-directory="/var/log/swiftmq/sinks"/>

Configuration Guide

Increase Log File Size and Reduce Retention

When running in an environment with high log volume and limited disk space, you may want to increase the log file size to reduce rotation frequency and decrease the number of retained generations to save space.

1. Set the size-limit property to a higher value (e.g., 4096 for 4 MB).
2. Set the number-old-logfile-generations property to a lower value (e.g., 5).
3. Restart the router or reload the configuration for changes to take effect.

<swiftlet name="sys$log" size-limit="4096" number-old-logfile-generations="5"/>

Disable Information Logging

To reduce log verbosity and disk usage, you may want to disable information-level logging while retaining warnings and errors.

1. Set the logfile-info-enabled property to false.
2. Leave logfile-warning-enabled and logfile-error-enabled as true.
3. Restart the router or reload the configuration for changes to take effect.

<swiftlet name="sys$log" logfile-info-enabled="false"/>

Store Log Files in a Custom Directory

For compliance or operational reasons, you may need to store log files in a specific directory (e.g., a dedicated log partition).

1. Set the logfile-info, logfile-warning, and logfile-error properties to absolute paths in the desired directory.
2. Ensure the directory exists and is writable by the SwiftMQ process.
3. Restart the router or reload the configuration for changes to take effect.

<swiftlet name="sys$log" logfile-info="/var/log/swiftmq/info.log" logfile-warning="/var/log/swiftmq/warning.log" logfile-error="/var/log/swiftmq/error.log"/>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$log">.

<swiftlet name="sys$log"> Properties

These properties are attributes of the <swiftlet name="sys$log"> entity.

Parameter	Type	Default	Mandatory	Reboot Required	Description
size-limit	Integer	1024	No	No	Logfiles do rotate by reaching this size (min: 1)
number-old-logfile-generations	Integer	50	No	No	Number old Logfile Generations to keep
logfile-info-enabled	Boolean	true	No	No	Info Logfile enabled
logfile-info	String	swiftmq_info.log	No	No	Logfile Information Messages
logfile-warning-enabled	Boolean	true	No	No	Warning Logfile enabled
logfile-warning	String	swiftmq_warning.log	No	No	Logfile Warning Messages
logfile-error-enabled	Boolean	true	No	No	Error Logfile enabled
logfile-error	String	swiftmq_error.log	No	No	Logfile Error Messages
logsink-directory	String	./	No	No	Directory where Logsinks will be stored

<swiftlet name="sys$log" size-limit="1024" number-old-logfile-generations="50" logfile-info-enabled="true" logfile-info="swiftmq_info.log" logfile-warning-enabled="true" logfile-warning="swiftmq_warning.log" logfile-error-enabled="true" logfile-error="swiftmq_error.log" logsink-directory="./"/>