Subsystem Level Overrides

Subsystem Level Overrides

A channel has its own filtering level, but a named subsystem can optionally have a different level. This is useful when several functional areas share the same channel and backends, while one area needs more or less verbosity.

A subsystem level override is global for the Logger. It is not tied to one channel and it is not a separate routing rule. For every channel that receives a record with that subsystem, the subsystem level replaces the channel level for that record.

Replacement semantics

The override is a replacement, not an additional threshold and not a minimum or maximum combined with the channel level.

For a channel configured at INFO:

Logme::Instance->SetSubsystemLevel(
  Logme::SID::Build("DSL"),
  Logme::LEVEL_DEBUG
);

DEBUG records from DSL may pass that channel even though ordinary DEBUG records do not.

Conversely:

Logme::Instance->SetSubsystemLevel(
  Logme::SID::Build("CLOUD"),
  Logme::LEVEL_WARN
);

INFO records from CLOUD are rejected even though ordinary INFO records pass the channel.

Without an override for the selected subsystem, the channel level is used normally.

Which subsystem is selected

A log record can receive its subsystem from several places. The effective priority is:

1. a SID passed explicitly to the logging call;
2. the subsystem assigned to the current thread with SetThreadSubsystem() or ThreadSubsystem;
3. the lexical SUBSID visible at the logging call;
4. an empty subsystem.

Example:

LOGME_SUBSYSTEM(SUBSID, "DSL");
const auto cloud = Logme::SID::Build("CLOUD");

LogmeI("uses DSL");
LogmeI(cloud, "uses CLOUD");

In the second call, the explicit CLOUD identifier takes precedence over the lexical SUBSID. A thread subsystem similarly takes precedence over lexical SUBSID, but an explicit subsystem still wins over the thread subsystem.

Interaction with blocked and allowed lists

Subsystem allow/block filtering and subsystem level overrides solve different problems:

• blocked and allowed decide whether a subsystem is permitted at all;
• a subsystem level decides which severity levels pass the channel for that permitted subsystem.

A blocked subsystem remains blocked regardless of its configured level. When the allowed list is non-empty, a named subsystem must be allowed before its level override can matter. Messages without a subsystem are not affected by subsystem allow/block lists and cannot have a named-subsystem level override.

C++ API

const auto dsl = Logme::SID::Build("DSL");

Logme::Instance->SetSubsystemLevel(dsl, Logme::LEVEL_DEBUG);

Logme::Level level;
if (Logme::Instance->GetSubsystemLevel(dsl, level))
{
  // An override is configured.
}

Logme::Instance->RemoveSubsystemLevel(dsl);
Logme::Instance->ClearSubsystemLevels();

Available methods:

void SetSubsystemLevel(const SID& sid, Level level);
bool GetSubsystemLevel(const SID& sid, Level& level);
void RemoveSubsystemLevel(const SID& sid);
void ClearSubsystemLevels();
bool HasSubsystemLevelOverrides() const;

SetSubsystemLevel() replaces an existing value for the same subsystem. An empty SID is ignored by SetSubsystemLevel() and is never returned by GetSubsystemLevel().

JSON configuration

Use the levels object inside subsystems:

{
  "subsystems": {
    "blocked": ["NOISE"],
    "allowed": ["DSL", "CLOUD"],
    "levels": {
      "DSL": "DEBUG",
      "CLOUD": "WARN"
    }
  }
}

The object keys are subsystem names and the values are level names. Level names are parsed case-insensitively.

Loading configuration replaces the complete set of subsystem level overrides. If subsystems.levels is absent, the loaded configuration clears previously configured subsystem levels. An empty subsystem name, a non-string value, an unsupported level, or a non-object levels field makes subsystem configuration parsing fail.

Runtime control

Show all subsystem filters and levels:

subsystem

Set or replace a level:

subsystem --set-level DSL DEBUG
subsystem --set-level CLOUD WARN

Inspect one subsystem:

subsystem --check DSL

The response reports Level: channel default when no override exists.

Remove one level or all levels:

subsystem --remove-level DSL
subsystem --clear-levels

subsystem --clear-levels clears only level overrides. subsystem --clear clears blocked subsystems, allowed subsystems, subsystem levels, and the legacy subsystem list.

Accepted runtime level names are case-insensitive. The command accepts these forms:

• debug
• info, information
• warn, warning
• err, error
• crit, critical

Performance behavior

The final level decision is made by the destination channel after the effective subsystem has been placed into the record context. The early logging precheck also applies the subsystem level when the effective subsystem is already known safely at the call site. When a thread subsystem can change the final choice, precheck remains conservative and allows normal record construction so the final channel check can make the authoritative decision.

Choosing between a channel and a subsystem level

Use a separate channel when the records need different backends, files, formatting, routing, or enable/disable state. Use a subsystem level override when the route should remain unchanged and only the severity threshold for one functional tag needs to differ.

channel level override   = different threshold for one output route
subsystem level override = different threshold for one functional tag across routes