Skip to content

Trace Swiftlet

Overview

The Trace Swiftlet provides a flexible and configurable tracing facility for SwiftMQ routers. It allows administrators and support engineers to capture detailed trace output from various internal components, directing trace messages to files or the console based on configurable predicates. Tracing is intended for advanced troubleshooting and should only be enabled under the guidance of technical support due to the potentially high volume of log output.

Features

Trace Spaces and Predicates

Tracing is organized into logical units called trace spaces, each of which can be independently enabled or disabled. Within each trace space, one or more predicates define specific filtering and output rules for trace messages. Each predicate specifies a SQL-LIKE pattern (using % as a wildcard) to match sub-entities within the trace space, and an output destination (either a file or the console). When a trace message is generated, it is evaluated against the predicates in its trace space, and if a predicate matches, the message is written to the specified output.

Predicates can be individually enabled or disabled, and their configuration (such as the output file or matching pattern) can be changed at runtime. The trace output includes a timestamp, the trace space name, the sub-entity (if any), and the message content.

Trace Spaces

A trace space represents a logical grouping of related trace messages, such as those from a specific Swiftlet or subsystem. Each trace space can be enabled or disabled as a whole. Spaces are defined as child elements under the Trace Swiftlet configuration.

Predicates

Predicates within a trace space determine which trace messages are captured and where they are written. Each predicate has an enabled flag, a SQL-LIKE pattern (using % as a wildcard) to match sub-entity names, and an output destination. The output can be a file (with automatic rolling and retention) or the console. Only messages matching the predicate's pattern are traced.

Output Destinations and File Rolling

Trace output can be directed to a file or to the console. When writing to a file, the Trace Swiftlet supports automatic file rolling based on a configurable maximum file size (in KB) and retains a configurable number of old trace file generations. This ensures that trace files do not grow indefinitely and that recent trace history is preserved for analysis.

Configuration Example:

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

Dynamic Configuration and Runtime Control

The Trace Swiftlet supports dynamic changes to its configuration at runtime. Administrators can enable or disable trace spaces and predicates, adjust predicate patterns, and change output destinations without restarting the router. This flexibility allows for precise and timely tracing during troubleshooting sessions. However, due to the potentially large volume of trace output, tracing should only be enabled when specifically advised by technical support.

Configuration Example:

<swiftlet name="sys$trace">
  <spaces>
    <space name="sys$routing" enabled="true">
      <predicates>
        <predicate enabled="false" filename="router-trace.log" value="rt$%"/>
      </predicates>
    </space>
  </spaces>
</swiftlet>

Trace File Management

The Trace Swiftlet manages trace file size and retention automatically. The maximum size of each trace file is configurable (in kilobytes), and when the limit is reached, the file is rolled over. A configurable number of old trace file generations are retained, ensuring that disk usage is controlled while preserving recent trace history for analysis.

Configuration Example:

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

Configuration Guide

Enable Tracing for a Specific Swiftlet

To capture trace output for a specific Swiftlet (e.g., the Queue Manager), define a trace space for that Swiftlet and add a predicate to direct output to the console or a file. This is useful when troubleshooting issues isolated to a particular subsystem.

  1. Add a new space under the Trace Swiftlet configuration with the name of the target Swiftlet (e.g., sys$queuemanager).
  2. Set the enabled attribute of the space to true.
  3. Add a predicate with a value of % (to match all sub-entities), set enabled to true, and specify the output filename (e.g., console or a file name).
<swiftlet name="sys$trace">
  <spaces>
    <space name="sys$queuemanager" enabled="true">
      <predicates>
        <predicate enabled="true" filename="console" value="%"/>
      </predicates>
    </space>
  </spaces>
</swiftlet>

Limit Trace File Size and Retention

To prevent trace files from consuming excessive disk space, adjust the maximum file size and the number of old trace file generations to retain. This is important for production environments where disk usage must be controlled.

  1. Set the max-file-size attribute on the Trace Swiftlet to the desired value in kilobytes (e.g., 20480 for 20 MB).
  2. Set the number-old-tracefile-generations attribute to the desired number of generations to keep (e.g., 10).
<swiftlet name="sys$trace" max-file-size="20480" number-old-tracefile-generations="10"/>

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>