rsyslog/runtime/AGENTS.md

AGENTS.md – Runtime subtree

These instructions apply to all files under runtime/, which implement the rsyslog core (message queues, networking backends, parsers, scheduler, stats collection, and process orchestration).

Purpose & scope

• Treat this tree as the authoritative implementation of the rsyslog engine. Changes here affect every module and deployment profile.
• Consult the top-level AGENTS.md and component-specific guides (e.g. plugins/AGENTS.md) when a change crosses directory boundaries.

Key components

• rsyslog.c / rsyslog.h: main entry point and daemon lifecycle helpers.
• modules.c, module-template.h: module loader contracts shared with plugins/ and contrib/.
• queue.c, wti.c, wtp.c: work queue implementation and worker threads. Disk-assisted mode creates two queue objects: an in-memory parent and a first-class disk child (pqDA). Disk queue semantics for .qi state, segment files, queue.onCorruption, quarantine, and runtime corruption handling apply to the DA child just as they apply to pure disk queues.
• tcpsrv.c, tcpclt.c, net*.c: TCP/TLS listeners and clients.
• parser.c, prop.c, template.c: core message parsing and property engine.
• statsobj.c, dynstats*.c: statistics registry and dynamic counters.
• timezones.c, datetime.c: time conversion helpers.
• yamlconf.c / yamlconf.h: YAML configuration frontend — parses .yaml/.yml files and produces the same cnfobj+nvlst trees that the RainerScript grammar produces, then feeds them into the shared cnfDoObj() backend in conf.c. Any change to config objects, statement types, template modifiers, or global parameters must be reflected here as well as in grammar/. See the rsyslog_config skill for parity rules.

Build & validation

• Efficient Build: Use make -j$(nproc) check TESTS="" to incrementally build the core, shared libraries, and test dependencies. This ensures that tests can dynamically load the runtime via -M../runtime/.libs.
• Bootstrap/Configure: Run ./autogen.sh and ./configure --enable-testbench only when build scripts change (configure.ac, Makefile.am, etc.) or if the Makefile is missing. Run these from the repository root.
• Run Tests: Prefer targeted test runs:
  • Directly invoke the most relevant shell test under tests/ (e.g. ./tests/queue-persist.sh).
  • Use make check TESTS='<script>.sh' when you need automake’s harness or Valgrind variants (*-vg.sh).
  • For configuration validation edits, run ./tests/validation-run.sh.
• When changing exported symbols, update runtime/Makefile.am and ensure the library version script (if touched) remains consistent with existing SONAME policies.

Coding expectations

• Follow COMMENTING_STYLE.md and add/update "Concurrency & Locking" blocks in files that manage shared state (queues, network sessions, statistics).
• Keep worker/thread behavior aligned with MODULE_AUTHOR_CHECKLIST.md rules: per-worker state stays in wrkrInstanceData_t, shared state is guarded in per-action data structures.
• Update doc/ai/module_map.yaml when locking guarantees, queue semantics, or exported helper APIs change so module authors know what to depend on.
• Update or create unit helpers (e.g. under tests/ or runtime/hashtable/) when you modify reusable primitives.

Coordination & documentation

• Notify module owners (via metadata or review notes) when adjusting module-template.h, initialization flows, or statistics surfaces consumed by plugins.
• Cross-reference user docs in doc/ if behavior visible to operators changes (configuration syntax, stats counters, TLS requirements, etc.).
• Leave ChangeLog and NEWS edits to the maintainers; do not modify those files in routine patches.

Debugging tips

• Enable extra runtime logging with export RSYSLOG_DEBUG="..." in tests (see tests/diag.sh) when chasing race conditions.
• Use the testbench Valgrind helpers by running the corresponding *-vg.sh scripts to flush out memory and threading regressions.