# 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

- Action Threads and Queue Engine (Developer-Oriented)

- Understanding rsyslog Queues

- General Queue Parameters

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

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.