Advanced Features

Advanced Features

This page collects logme features that are not required for the first logging call, but become important in real applications.

The basic case is intentionally simple: include the header and write a message.
The features below are meant for situations where logging stays in production code, runs in hot paths, or has to help diagnose a running process without restart.

---

Message frequency control

Some warnings are useful once, but harmful when printed thousands of times.

logme provides built-in helpers for limiting how often a particular message appears.
This is useful for repeated warnings, polling loops, retry loops, and other hot paths where the same condition can be reported continuously.

Examples:

LogmeW_Once("configuration file is missing, using defaults");
LogmeI_Every(1000, "worker is still waiting");
LogmeW_Collapse(10, "backend is still unavailable");
LogmeW_CollapseEvery(1000, "backend is still unavailable");
LogmeW_CollapseIgnore("request_id=[0-9]+", 10, "request_id=%llu backend is still unavailable", requestId);
LogmeW_CollapseIgnoreEvery("request_id=[0-9]+", 1000, "request_id=%llu backend is still unavailable", requestId);

..._Once prints only the first matching call.
..._Every(ms, ...) prints at most once per specified interval without a repeat summary.
..._Collapse(limit, ...) writes the first occurrence and then aggregates repeated attempts by count with the same comparison key at the same call site.
..._CollapseEvery(intervalMs, ...) writes the first occurrence and then aggregates repeated attempts by time interval.
..._CollapseIgnore(...) and ..._CollapseIgnoreEvery(...) do the same comparison after removing regex-matched volatile substrings from the formatted message.

The same idea is also available through override scopes such as LOGME_ONCE4THIS, LOGME_EVERY4THIS, LOGME_ONCE4CALL, and LOGME_EVERY4CALL. Collapse is implemented separately through CollapseContextCache and Context::ApplyCollapse().

See Override Scopes, Collapse Logging, and OnceEvery example.

---

Early filtering and precheck

In many applications the expensive part of logging is not the final write.
It is the work done before the logger knows whether the message will be emitted: building strings, calling helper functions, collecting diagnostics, or formatting arguments.

logme tries to reject disabled messages as early as possible.

When a ChannelPtr is passed as the first argument, the macro can check the channel state before evaluating the remaining arguments:

LogmeI(channel, "state: %s", BuildExpensiveState().c_str());

For preparation code that should run only when the record will really be written, logme provides the ..._Do macros:

LogmeI_Do(channel->GetID(), value = PrepareValue(), "value=%d", value);

This is especially useful for diagnostics that are valuable when enabled, but too expensive to calculate unconditionally.

See Precheck example and Message Filtering.

---

Boot and early logging

Startup failures are often the hardest to diagnose because normal configuration may not be loaded yet.

logme supports early logging so that messages produced during startup are not lost before the full logging graph is configured.
This is useful for configuration loading, backend initialization, path resolution, certificate/key checks, and other early application stages.

The important point is that logging can begin before the final runtime configuration is available.
After configuration is loaded, the application can switch to the normal channel/backend setup.

---

Runtime control

logme can expose a control server that allows inspecting and changing logging behavior in a running process.

This is different from simply loading configuration at startup.
Runtime control is intended for short diagnostic sessions: enable a channel, change a level, add a simple backend, inspect current state, or adjust subsystem filters without restarting the application.

The bundled logmectl tool is the command-line client for this interface.

See Runtime Control, Control Server, logmectl, and logmeweb.

---

Startup control from environment

Applications can opt in to applying control commands from environment variables during startup. logme does not read those variables automatically; the application must call ApplyEnvironmentControl() and pass the desired policy and error mode.

This makes environment overrides useful for controlled diagnostic launches without turning the process environment into an implicit configuration source.

See Environment Control and Control Policies.

---

Recent-history capture

RingBufferBackend can keep only the last N formatted records in memory. This can be used as backtrace-style log history: keep recent diagnostic context and dump it only after an error or failed request.

See Ring Buffer Backend and Recent-History Capture.

---

Trace points

Trace points are dormant diagnostic call sites that count hits while disabled and start writing normal log records only when enabled through runtime control. They are useful for production diagnostics where the call site should remain cheap and silent until an operator explicitly turns it on.

Trace points can be listed, enabled, disabled, and reset with logmectl, or managed visually through logmeweb.

See Trace Points, Runtime Control, and logmeweb.

---

Native formatting styles

logme supports the traditional printf-style logging macros and C++ formatting/streaming styles where enabled by the build configuration.

This makes it possible to use logme in older C/C++ codebases without forcing a full formatting-style migration, while still allowing modern C++ projects to use native formatting support.

See Logging Macros, FormatApi example, and CMake Integration.

---

Structured output without changing call sites

A normal log call can be rendered as text, JSON, or XML depending on channel output flags and configuration.

This means application code does not have to be rewritten just because the output format changes.
The same logical record can be written as a readable text line or as a structured event.

See OutputFlags, Log Output Format, and StructuredOutput example.

---

Obfuscation and protected diagnostics

Production logs may contain sensitive data.

logme includes obfuscation support and tools for working with protected logs.
This allows keeping diagnostics useful while reducing the risk of exposing raw sensitive values.

See Security, Log Encryption, and logmeobf.

---

Why these features belong together

All these features have the same goal: make detailed logging practical outside a debugger.

They reduce noise, avoid unnecessary hot-path work, preserve startup diagnostics, and allow changing logging behavior only when a problem actually needs investigation.