imdiag: Diagnostic instrumentation¶

Module Name:: imdiag
Author:: Rainer Gerhards
Available since:: at least 5.x

Purpose¶

The imdiag input module exposes a TCP-based diagnostics and control channel that can inject messages into the main queue, wait for queues to drain, coordinate statistics reporting, and exercise other helper functions used by the rsyslog testbench. While imdiag is primarily intended for automated testing, it can also be used to diagnose production systems. Because the interface permits queue control and message injection, it must only be exposed to trusted hosts.

Configuration Parameters¶

Note

Parameter names are case-insensitive; camelCase is recommended for readability.

Module Parameters¶

Parameter	Summary
AbortTimeout	Starts a watchdog thread that aborts rsyslog if it runs longer than the configured time limit.
ListenPortFileName (module scope)	Path of the file to which imdiag writes its chosen TCP listen port number, set at module load time.
MainMsgQueueTimeoutShutdown	Sets the main message queue shutdown timeout at config load time.
MainMsgQueueTimeoutEnqueue	Sets the main message queue enqueue timeout at config load time.
InputShutdownTimeout	Sets the input shutdown timeout at config load time.
DefaultActionQueueTimeoutShutdown	Sets the default action queue shutdown timeout at config load time.
DefaultActionQueueTimeoutEnqueue	Sets the default action queue enqueue timeout at config load time.
InjectDelayMode	Sets the flow-control classification applied to messages injected by imdiag.
MaxSessions	Limits the number of concurrent diagnostic control connections accepted.

Input Parameters¶

Parameter	Summary
ListenPortFileName	Writes the port chosen for the diagnostic listener to the named file.
ServerRun	Creates the imdiag TCP listener on the specified port (`0` selects an ephemeral port).
ServerStreamDriverMode	Accepts a numeric stream driver mode value, but imdiag forces the plain TCP driver so the setting is ignored.
ServerStreamDriverAuthMode	Accepts a stream driver authentication mode string, but imdiag always uses the plain TCP driver so the value has no effect.
ServerStreamDriverPermittedPeer	Accepts permitted peer identifiers for compatibility, but the plain TCP driver used by imdiag does not enforce them.
ServerInputName	Overrides the `inputname` property for the diagnostic TCP listener’s own log messages.

Examples¶

Minimal configuration for testbench integration¶

This example loads imdiag, starts the diagnostic listener on an ephemeral port, and records the chosen port for the testbench to read.

module(load="imdiag")
input(type="imdiag"
      listenPortFileName="/var/run/rsyslog/imdiag.port"
      serverRun="0")

YAML-only testbench configuration¶

In YAML-only mode the testbench preamble uses the testbench_modules: key (an alias for modules: reserved for testbench infrastructure) so that it does not conflict with the test’s own modules: section.

version: 2

global:
  debug.abortOnProgramError: "on"

testbench_modules:
  - load: "../plugins/imdiag/.libs/imdiag"
    listenportfilename: "test.imdiag.port"
    aborttimeout: "580"
    mainmsgqueuetimeoutshutdown: "10000"
    mainmsgqueuetimeoutenqueue: "30000"
    inputshutdowntimeout: "60000"
    defaultactionqueuetimeoutshutdown: "20000"
    defaultactionqueuetimeoutenqueue: "30000"

modules:
  - load: "../plugins/imtcp/.libs/imtcp"

inputs:
  - type: imdiag
    port: "0"
  - type: imtcp
    port: "0"

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project