The daily edition.

Scope: Rocket Enterprise Developer 12.0 for Eclipse (UNIX), Consolidated Tracing Facility (CTF) configuration through ctf.cfg. Everything below comes from the 12.0 UNIX documentation bundle enterprisedevelopereclux_ug_120.

Why this matters

The Consolidated Tracing Facility is a tracing infrastructure for producing diagnostic information from Rocket software components and your own programs. You describe what to capture in a side file, the CTF configuration file: which application to trace, the severity level of messages to capture, and the emitters (text or binary, for example) that produce the output (Consolidated Tracing Facility (Diagnostics)).

The configuration is not a flat list of switches. Components form a tree, and both trace levels and output destinations flow down that tree unless you override them. Knowing the inheritance rules lets you keep one noisy component from drowning the rest of the trace, and lets you route one component's events to a different place.

Enabling CTF and where the file lives

CTF reads its configuration from the file named by the MFTRACE_CONFIG environment variable. Optionally, MFTRACE_LOGS names the directory for trace files; if it is not set, the current folder is used. If the configuration file specifies a trace file location, that location overrides MFTRACE_LOGS (To Enable CTF Tracing).

export MFTRACE_CONFIG=/home/usr/ctf/ctf.cfg

The file is processed during run-time system initialization. It must be a text file of name-value pairs, one entry per line, and lines beginning with # are comments (Configuration File for CTF). Because it is read at initialization, set it up before you start the application.

Levels: off by default, and inherited

Tracing is disabled for all components by default. The documented minimum to turn on run-time system tracing is an mftrace.level or mftrace.level.mf.rts entry. For example, a file containing only mftrace.level=error is enough for any process that produces a run-time system error to write a trace entry for event 255, with no mf.rts properties needed (CTF Tracing Examples).

mftrace.level sets the default threshold for all components. Its values are case-insensitive, and each includes the more severe ones below it (mftrace.level):

• NONE: no events are traced (this is the default).
• DEBUG: all events, the most verbose output.
• INFO: INFO, WARN, ERROR and FATAL events.
• WARN: WARN, ERROR and FATAL events.
• ERROR: ERROR and FATAL events.
• FATAL: only FATAL events.

Several mftrace.level entries may appear, but a later one overrides the earlier. mftrace.level.component-name then overrides the default for one component. When a component has no level of its own, it inherits its parent's level, and a component's parent is the one to its left in the dotted name: for mf.rts.subsystem, mf is the parent of rts, and rts is the parent of subsystem. A component-level entry applies to that component and any components that inherit from it (mftrace.level.component-name).

mftrace.level=debug
mftrace.level.mf.rts=warn

This documented example traces everything at DEBUG except the run-time system component mf.rts (and its children), which is limited to WARN and above.

Destinations: cumulative by default, replaceable with parentheses

Output destinations follow the same tree logic. mftrace.dest names the default emitters as a comma- or space-separated list; if you do not set it, TEXTFILE is assumed. Several mftrace.dest definitions for an emitter are cumulative rather than replacing one another (mftrace.dest).

mftrace.dest=TEXTFILE,BINFILE

mftrace.dest.component-name adds destinations for one component. If you do nothing, a component inherits its parent's destinations, and multiple definitions for the same component are also cumulative. The syntax is mftrace.dest.component-name=[(]emitter-list[)], and the optional parentheses change the meaning: with them, the component's events go only to the listed emitters and not to any inherited from the parent (mftrace.dest.component-name).

Compare the two documented examples:

# Additive: mf.rts events go to BINFILE and to the default TEXTFILE
mftrace.level=INFO
mftrace.dest=TEXTFILE
mftrace.dest.MF.RTS=BINFILE

# Replacement: mf.rts events go ONLY to BINFILE; everything else to TEXTFILE
mftrace.level=INFO
mftrace.dest=TEXTFILE
mftrace.dest.MF.RTS=(BINFILE)

In both, children such as mf.rts.err and mf.rts.mem follow mf.rts.

A practical combined file

The documented binary-trace example shows how these settings fit together with emitter properties and component properties:

mftrace.dest = binfile
mftrace.emitter.binfile#location  = /home/usr/logs
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true

The pgm and pgmload properties are what reveal program entry, exit, load and cancel events. The documentation notes that to see which programs ran before a run-time error you set PGM, and to see where they were loaded from and when they were cancelled you also set PGMLOAD (To Enable CTF Tracing; CTF Tracing Examples). Choosing binary output also lets you examine the trace in the CTF Viewer (Consolidated Tracing Facility (Diagnostics)).

Caveats to remember

• Entries are cumulative for destinations but last-one-wins for levels: a later level entry overrides an earlier one, while repeated destination entries add up.
• A component-level setting cascades to its children, so a setting on mf.rts also affects mf.rts.err and mf.rts.mem.
• For JVM environments, an mfjvm.ctf file on the classpath can be used instead, in the same format as ctf.cfg, but MFTRACE_CONFIG takes precedence when both are set (To Enable CTF Tracing).

Takeaway

CTF is off until you set a level, and both levels and destinations inherit down the dotted component tree: set a broad default, override it per component, and put the emitter list in parentheses in mftrace.dest.component-name when a component's events should go only to those emitters rather than in addition to the inherited ones (mftrace.dest.component-name).