Routing

Routing

This page describes the actual routing and filtering pipeline used by logme.

Routing in logme is not a simple channel-to-backend dispatch. A log message passes through a well-defined sequence of global filters, per-channel checks, and routing stages before it is finally written.

---

High-Level Pipeline

At a high level, message processing consists of the following stages:

1. Global condition check
2. Override checks (rate / count limits)
3. Subsystem filtering
4. Level filtering (initial channel)
5. Message formatting
6. Per-channel processing and routing
7. Backend delivery
8. Error channel dispatch (optional)

Each stage may drop the message, stopping further processing.

---

Global Filters

Condition Callback

Processing begins with a global Condition callback, installed via:

Logger::SetCondition()

• The condition callback is evaluated before any other processing.
• By default, the condition always returns true.
• If the condition returns false, the message is dropped immediately.

Typical uses:

• Muting all log output
• Suppressing logs for specific threads
• Temporarily disabling logging without reconfiguration

---

Override Checks

If an override is specified for the message, it is evaluated next.

Overrides may impose:

• A maximum message rate
• A maximum number of messages of a given type

If any override limit is exceeded, the message is dropped.

Overrides provide a way to protect the system from log flooding.

---

Subsystem Filtering

Each message may optionally specify a subsystem.

• If a subsystem is explicitly specified
• And that subsystem is marked as disabled

The message is dropped.

Subsystem filtering occurs before channel-level filtering.

---

Level Filtering (Initial Channel)

Before formatting, the message level is compared against the level of the target channel.

If the message level is lower than the channel level, the message is dropped.

This ensures that unnecessary formatting work is avoided.

---

Message Formatting

Only after all global and initial channel filters pass is the message formatted into its final string representation.

Formatting is performed once and reused for all subsequent routing steps.

---

Per-Channel Processing

Each channel processes the message independently, using its own configuration.

For each channel in the routing chain:

1. Enabled check
   If the channel is disabled via SetEnabled(false), processing stops for this channel.

2. Level check
   The message level is compared against the channel level.
   If the check fails, processing stops for this channel.

3. Display Filter
   If a display filter callback is installed, it is invoked before output.
   The filter may suppress the message.

4. Linked channel propagation
   If the channel has a linked (parent) channel, the message is forwarded to it.

5. Backend delivery
   The message is delivered to all backends attached to the channel.

Each channel uses its own OutputFlags and level settings.

---

Error Channel Dispatch

At the final stage, the logger checks whether an error channel is configured via:

Logger::SetErrorChannel()

If an error channel exists and the message level is Error or Critical, the message is forwarded to the error channel for additional processing.

---

Key Properties

• Routing is deterministic and ordered
• Filtering happens as early as possible
• Formatting occurs only once
• Channels do not inherit configuration from each other
• The same message may be output differently by different channels

This pipeline allows logme to remain flexible while keeping runtime overhead low and predictable.