Error Channel

Error Channel

logme supports designating one of the channels as a global error channel. This mechanism is intended for centralized collection and handling of errors occurring across the entire system.

---

Overview

The error channel is a special channel that automatically receives copies of all log messages with severity Error or CriticalError, regardless of the channel they were originally logged to.

This makes it possible to:

• aggregate all errors into a single log file
• display errors in a dedicated console window
• forward errors to monitoring, alerting, or diagnostic backends
• simplify diagnostics and postmortem analysis

The error channel acts as an additional routing destination and does not replace or interfere with normal channel routing.

---

How Error Routing Works

When a log message is emitted with level Error or CriticalError, logme applies the following algorithm:

1. The message is evaluated against the original target channel configuration.
2. Subsystem and level filters of that channel are applied.
3. If the message is accepted, it is delivered to the channel backends.
4. The same message is then duplicated and routed to the error channel.

The error channel therefore acts as a secondary sink for error-level messages.

---

Filtering Rules and Guarantees

No Filter Bypass

A message is not routed to the error channel if it was dropped earlier due to:

• an unapproved subsystem
• level filtering on the original target channel

This means:

The error channel only receives messages that successfully passed filtering on their original channel.

This behavior is intentional and guarantees that:

• global error aggregation does not override channel policies
• disabled subsystems stay completely silent
• log volume remains predictable

Practical Implication

If a channel filters out Error messages entirely, no error duplication will occur for that channel, even if an error channel is configured.

---

Intended Usage Pattern

The channel designated as the error channel is usually not used for direct logging. Instead, it serves as a central aggregation point for error-level events coming from other channels.

Typical architecture:

• functional channels
  • apply domain-specific filtering
  • route to files, consoles, or remote backends
• error channel
  • receives only Error / CriticalError messages
  • routes them to a dedicated backend

This separation allows keeping normal logs clean while still having a complete overview of system failures.

---

File-Based Error Channel (Recommended)

The most common and recommended configuration is routing all errors into a dedicated log file.

Advantages:

• single chronological error stream
• easy monitoring and alerting
• simplified log rotation and archiving
• clear separation from informational logs

Example: Error Channel with File Backend

LOGME_CHANNEL(ech, "errors");

auto pch = Logme::Instance->CreateChannel(ech);

pch->AddBackend(
  std::make_shared<FileBackend>(
    pch,
    "errors.log"
  )
);

Logme::Instance->SetErrorChannel(ech);

In this configuration:

• every Error and CriticalError message
• from any channel in the system
• is written to errors.log
• provided it passed filtering on the original channel

---

Console-Based Error Channel

For development and debugging scenarios, the error channel may be connected to a console backend.

LOGME_CHANNEL(ech, "errors");

auto pch = Logme::Instance->CreateChannel(ech);
pch->AddBackend(std::make_shared<ConsoleBackend>(pch));

Logme::Instance->SetErrorChannel(ech);

Console Duplication Caveat

If the original channel already has a console backend and the error channel also uses a console backend, the same error message will appear twice in the console.

This is expected behavior, because:

• the message is delivered independently to the original channel
• and again to the error channel

To avoid duplication, ensure that only one of the channels outputs errors to the console.

---

Common Configuration Mistakes

• Using the error channel for direct logging
• Expecting the error channel to bypass filters
• Attaching verbose backends (e.g. debug console) to the error channel
• Forgetting that duplication happens only after successful filtering

---

Summary

• The error channel provides centralized error aggregation.
• It receives copies of Error and CriticalError messages.
• Original channel filtering is always respected.
• The error channel is usually passive and not logged to directly.
• A dedicated file backend is the most common and recommended setup.