Trace Swiftlet

Overview

The Trace Swiftlet provides configurable tracing capabilities for SwiftMQ routers, allowing detailed logging of internal events and message flows. It supports multiple trace spaces, each of which can be selectively enabled and configured with predicates to filter and direct trace output to specific destinations. Due to the potential for heavy log output, tracing should only be enabled when specifically advised by technical support.

Features

Trace Spaces and Predicates

Tracing is organized into 'trace spaces', each representing a logical area or component of the router (such as protocol handlers, queue managers, etc.). Each trace space can be enabled or disabled independently. Within each trace space, you can define multiple predicates. A predicate specifies a SQL-like filter (using % as a wildcard) that matches trace events within the space. Each predicate can be enabled or disabled individually.

Predicates also define the output destination for matching trace events. The destination is specified by the filename property, which can be set to console for standard output or to a file path for file-based logging. When a file is used, the Trace Swiftlet manages file rollover and retention according to the configured limits. Only trace events matching an enabled predicate's filter will be logged to its destination.

Predicate Filtering

Predicates use SQL-like patterns to match sub-entities within a trace space. For example, a predicate value of protocolhandler% would match all sub-entities starting with protocolhandler. The % character acts as a wildcard. This allows fine-grained control over which trace events are captured and where they are logged.

Output Destinations

Trace output can be directed to either the console (console) or to a file. When logging to a file, the Trace Swiftlet automatically manages file rollover based on the max-file-size property. It also retains a configurable number of old trace file generations, as specified by the number-old-tracefile-generations property.

Configuration Example:

<swiftlet name="sys$trace">
  <spaces>
    <space name="protocolhandler" enabled="true">
      <predicates>
        <predicate name="all" filename="console" value="%"/>
      </predicates>
    </space>
  </spaces>
</swiftlet>

Trace File Management

When trace output is directed to a file, the Trace Swiftlet enforces a maximum file size (in KB) as specified by the max-file-size property. Once the file reaches this size, it is rolled over and a new file is started. The number of old trace file generations to retain is controlled by the number-old-tracefile-generations property. This ensures that trace logging does not consume unlimited disk space.

Configuration Example:

<swiftlet name="sys$trace" max-file-size="20480" number-old-tracefile-generations="10">
  <spaces>
    <space name="queuemanager" enabled="true">
      <predicates>
        <predicate name="errors" filename="/var/log/swiftmq/trace.log" value="error%"/>
      </predicates>
    </space>
  </spaces>
</swiftlet>

Configuration Guide

Enable Tracing for a Specific Component

Use this scenario when technical support requests detailed trace logs for a specific router component, such as the protocol handler. This configuration enables tracing for the relevant trace space and directs all output to the console.

Identify the trace space corresponding to the component (e.g., protocolhandler).
Enable the trace space by setting its enabled attribute to true.
Add a predicate with a value of % to capture all events, and set the filename to console.

<swiftlet name="sys$trace">
  <spaces>
    <space name="protocolhandler" enabled="true">
      <predicates>
        <predicate name="all" filename="console" value="%"/>
      </predicates>
    </space>
  </spaces>
</swiftlet>

Trace Errors to a File with Rollover

Use this scenario to capture only error-related trace events for the queue manager and write them to a file with rollover and retention. This is useful for long-term diagnostics without overwhelming disk space.

Enable the queuemanager trace space.
Add a predicate that matches error events (e.g., value="error%"), and specify a file path for the filename.
Optionally, adjust max-file-size and number-old-tracefile-generations to control file management.

<swiftlet name="sys$trace" max-file-size="5120" number-old-tracefile-generations="5">
  <spaces>
    <space name="queuemanager" enabled="true">
      <predicates>
        <predicate name="errors" filename="/var/log/swiftmq/errors.log" value="error%"/>
      </predicates>
    </space>
  </spaces>
</swiftlet>

Configuration Reference

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

`<swiftlet name="sys$trace">` Properties

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

Parameter	Type	Default	Mandatory	Reboot Required	Description
`max-file-size`	Integer	`10240`	No	No	Max. Tracefile Size (KB)
`number-old-tracefile-generations`	Integer	`50`	No	No	Number old Tracefile Generations to keep

<swiftlet name="sys$trace" max-file-size="10240" number-old-tracefile-generations="50"/>

`<spaces>` in `<swiftlet name="sys$trace">`

Trace Space Definitions

Each <space> entry is identified by its name attribute (the Space).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`enabled`	Boolean	`false`	No	No	Enables/Disables the Space

<swiftlet name="sys$trace">
  <spaces>
    <space name="..."/>
  </spaces>
</swiftlet>

`<predicates>` in `<spaces>`

Predicate Definitions

Each <predicate> entry is identified by its name attribute (the Predicate).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`enabled`	Boolean	`true`	No	No	Enables/Disables this Predicate
`filename`	String	—	Yes	No	Output Filename
`value`	String	—	Yes	No	SQL-Like Predicate that selects from the Trace Stream

<swiftlet name="sys$trace">
  <spaces>
    <space name="...">
      <predicates>
        <predicate name="..." filename="..." value="..."/>
      </predicates>
    </space>
  </spaces>
</swiftlet>