Developer Overview: rsyslog Engine¶

Comprehensive technical overview of rsyslog’s core engine, queue types, concurrency handling, and worker thread model, aimed at contributors and advanced users.

Overview¶

rsyslog processes messages through a modular architecture built around queues, rulesets, and actions. The design enables high throughput, flexible routing, and resilience under load or failure conditions.

Key Components¶

Inputs: Modules that receive messages from various sources (e.g., imtcp, imudp).
Rulesets: Contain filters and actions; can be invoked by inputs or other rulesets.
Actions: Output or processing steps (e.g., omfile, omfwd).
Queues: Decouple producers from consumers, manage flow control, and ensure durability.

Queue Types¶

direct: No buffering; messages are handed directly to the action. Lowest latency but action must keep pace.
in-memory: Stored in RAM (LinkedList or FixedArray); volatile but fast.
disk-assisted (DA): Combination of in-memory (primary) and on-disk spillover when memory fills.
disk-only: Persistent on-disk storage; highest durability, higher latency.

Concurrency Model¶

Each action may have its own queue and multiple worker threads.
Worker threads dequeue messages in batches and execute the action logic.
Thread safety is enforced via locks or atomic operations where state is shared.
Avoid blocking operations in action workers; prefer non-blocking I/O.

Concurrency Handling in Detail¶

Worker threads per action are configured with queue.workerThreads.
Batching improves throughput but may introduce reordering between batches.
Synchronization primitives (mutexes, RW locks) are used only when necessary for shared state in pData.
Atomic counters and memory barriers ensure correctness without excessive locking.
Actions must clearly signal transient vs. permanent failures to allow the queue engine to handle retries or discards appropriately.

Queue Flow (Mermaid Diagram)¶

        flowchart LR
  Inputs[Inputs] --> MainQ[Main Queue]
  MainQ --> Rules[Rulesets]
  Rules -->|Filter match| ActQ1[Action Queue 1]
  Rules -->|Filter match| ActQ2[Action Queue 2]
  ActQ1 --> W1[Workers 1]
  ActQ2 --> W2[Workers 2]
  W1 --> A1[Action 1]
  W2 --> A2[Action 2]

Backpressure & Flow Control¶

High-water mark: When reached, producers block or slow down.
Low-water mark: Normal operation resumes below this threshold.
Discard policy: Drop lower-priority messages first when full.
Timeouts: Control enqueue blocking and shutdown grace periods.

Error Handling¶

Transient errors: Retries with exponential backoff.
Persistent errors: Drop, dead-letter queue, or keep retrying based on configuration.
DA/disk queues: Preserve messages across restarts.

Cross-References¶

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

Contributing: Source & docs: rsyslog source project