IBM® Informix® mttrace — Reference

mttrace is an internal / support-grade tracer for the Informix® MT (MultiThreaded) subsystem — the engine's virtual-processor and thread-scheduler layer. It switches on the engine's built-in trace instrumentation for chosen components or sessions, buffers the events in the server's shared memory, and lets you view or dump them live or from a shared-memory dump file. This page is a reference for the version shipped with IBM Informix Dynamic Server 14.10.FC13W3.

It is a Linux server side utility: it runs on the database host (not on a client), normally as user informix, and attaches directly to the running server's shared-memory segment. The usual environment must be in place (INFORMIXDIR, INFORMIXSERVER, sqlhosts, onconfig); failure paths report incorrect permissions, server-not-found, or shared-memory attach errors.

Command reference

mttrace on|off|empty|view|session|info|add|reset
        -c <comp> <level>
        -f
        -h
        -i <shfile>
        -n
        -s <sid>
        -t

Subcommands:

Options:

Trace levels

Set per component with -c <comp> <level>. The CLI carries off internally as an “explicitly disable” sentinel and collapses it to 0 when writing to shared memory.

Example — enable medium tracing for the buffer manager:

mttrace on -c MT_TRC_BFR_MGR med

Trace components

There are 121 components, ids 0–120. The -c handler matches the component name and uses the matched id as the index into the per-component trace-level array in server shared memory. Names and ids below are exact. The C header for these is provided as mt_trc_comp.h.

Trace record layout

Each record in a trace buffer is a fixed 40-byte (0x28) header followed by a packed argument area. Records sit back-to-back in each buffer; the reader steps forward by reclen. A reclen of 0 marks an empty slot / end. Offsets are exact; field names are reconstructed from the printed column headers and behaviour. Fields marked [-f] are only printed in full view (mttrace view -f).

typedef struct mt_trc_rec {
    uint8_t   narg;       /* 0x00 */
    uint8_t   vp;         /* 0x01  [-f] */
    uint16_t  msgid;      /* 0x02  index into the message catalog */
    uint16_t  resv04;     /* 0x04 */
    uint16_t  reclen;     /* 0x06  record length; 0 = empty */
    uint16_t  line;       /* 0x08 */
    uint16_t  fileid;     /* 0x0a  -> source file name */
    uint16_t  sesid;      /* 0x0c  [-f] */
    uint16_t  resv0e;     /* 0x0e */
    uint64_t  rstcb;      /* 0x10  [-f] */
    uint64_t  transp;     /* 0x18  [-f] */
    uint64_t  timestamp;  /* 0x20 */
    /* 0x28: narg packed argument entries */
} mt_trc_rec_t;

Argument encoding

The message template selected by msgid is a printf-style string. Its Nth % conversion consumes the Nth argument from the record's argument area. Each argument carries a type tag that selects a renderer:

On the wire each argument is tag + width: fixed 4-, 8-, or 16-byte values, or a variable-length form that carries a 2-byte big-endian length. The argument area is therefore a compact TLV stream that the formatter expands into the trailing message text.

view and view -f output

view snapshots the trace buffers, then walks and prints every record. The -f flag widens the per-record prefix to the full record. Columns:

• plain view — FileName  Line  Timestamp  <message>
• view -f — FileName  Line  Timestamp  VP  SesID  rstcb  transp  <message>

The full-view header row is:

FileName     Line  Timestamp            VP  SesID rstcb      transp     Trace Record

The Timestamp column renders either as a raw integer or as a formatted date/time (YYYY-MM-DD HH:MM:SS, or HH:MM:SS.mmm). Because each message template embeds its own function name, a record is self-identifying — you can tell which engine routine emitted it even without the FileName/Line columns.

Message catalog

The trace-point message catalog holds 602 entries. A record's msgid indexes this table directly; msgids 0–600 are the live templates and 601 is a build sentinel. Each template is the printf-style format string expanded with the record's arguments (see Argument encoding).

Caveats

This is an internal / support diagnostic. Component ids, the record layout, and the message catalog can change between engine versions — everything here is specific to IDS 14.10.FC13W3.

A diagnostic oninit build might expose more details.