Log Swiftlet

Overview

The Log Swiftlet provides a centralized logging facility for the SwiftMQ router. It manages log output for informational, warning, and error messages, writing them to separate log files with configurable rotation and retention policies. This Swiftlet ensures that all system and application events are persistently recorded for monitoring and troubleshooting.

Features

Log File Management and Rotation

The Log Swiftlet writes log messages to files dedicated to information, warning, and error levels. Each log file has a configurable maximum size, after which it is rotated. The number of old log file generations to retain is also configurable, allowing administrators to control disk usage and log retention. Log files are created in the working directory or a specified directory, and directories are created as needed. The log file names and their enabled/disabled status can be changed at runtime, with the Swiftlet seamlessly switching to new files without requiring a restart.

Log Levels and Files

Three log levels are supported: information, warning, and error. Each level can be enabled or disabled independently. By default, logs are written to swiftmq_info.log, swiftmq_warning.log, and swiftmq_error.log respectively, but these file names can be customized. If multiple log levels are configured to use the same file, the Swiftlet efficiently shares file handles to avoid redundant output.

Log Rotation and Retention

When a log file reaches the configured size limit (in kilobytes), it is rotated. The Swiftlet keeps a configurable number of old generations for each log file, automatically deleting the oldest files when the limit is exceeded. This ensures that log files do not consume excessive disk space while retaining recent log history for analysis.

Configuration Example:

<swiftlet name="sys$log" size-limit="2048" number-old-logfile-generations="20" logfile-info="/var/log/swiftmq/info.log" logfile-warning="/var/log/swiftmq/warning.log" logfile-error="/var/log/swiftmq/error.log"/>

Dynamic Log Level Control

Logging for each level (information, warning, error) can be enabled or disabled at runtime. When a log level is disabled, the Swiftlet records a configuration event in the corresponding log file indicating that logging for that level has been turned off. This allows administrators to reduce log verbosity or suppress certain types of messages without restarting the router. Changes to log file names or enabled status are applied immediately and safely using internal locking mechanisms.

Configuration Example:

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

Custom Log Sinks

The Log Swiftlet supports the creation of custom log sinks, which are additional log files that can be created programmatically for specific purposes. Log sinks are stored in a configurable directory, and their file names are determined by the sink name. This feature is useful for modules or applications that require separate logging streams beyond the standard information, warning, and error logs.

Logsink Directory

The directory where custom log sinks are stored can be specified via the logsink-directory property. By default, log sinks are created in the router's working directory, but this can be changed to any accessible path.

Configuration Example:

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

Configuration Guide

Increase Log File Size and Reduce Retention

To accommodate higher log volume and reduce disk usage by keeping fewer old log files, increase the log file size limit and decrease the number of old generations.

1. Edit the routerconfig.xml file.
2. Set the size-limit attribute to the desired size in kilobytes (e.g., 4096 for 4MB).
3. Set the number-old-logfile-generations attribute to the desired retention count (e.g., 10).
4. Restart the router for changes to take effect.

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

Disable Information Logging

To reduce log verbosity and disk usage, disable the information log while keeping warning and error logs enabled.

1. Edit the routerconfig.xml file.
2. Set the logfile-info-enabled attribute to false.
3. Save the configuration and restart the router, or apply the change at runtime if supported.

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

Change Log File Locations

To store log files in a custom directory, update the file paths for each log level.

1. Edit the routerconfig.xml file.
2. Set the logfile-info, logfile-warning, and logfile-error attributes to the desired absolute or relative paths.
3. Ensure the specified directories are writable by the router process.
4. Restart the router 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="./"/>