Message Filtering

Message Filtering and Callbacks

logme supports fine-grained control over message emission.

---

Release Logging

By default, logging may be disabled in Release builds.

To force-enable logging in Release, define the macro:

• LOGME_INRELEASE

When LOGME_INRELEASE is defined, logging calls remain active in Release builds and messages follow the same filtering and routing pipeline as in Debug.

---

Condition Callback (Global Filter)

logme provides a global condition callback that runs before any message processing. It can be installed via:

Logme::Instance->SetCondition(...);

Behavior:

• The default condition always returns true.
• The condition callback is evaluated before formatting and routing.
• If the callback returns false, the message is discarded immediately.

Typical uses:

• Temporarily muting all logging in the application
• Suppressing logs for specific threads
• Implementing dynamic runtime policies (e.g., based on environment or state)

Because the condition callback runs early, it is an efficient way to pause or block logging without changing channel configuration.

---

Filtering pipeline

For normal LogmeX macros, filtering happens in several stages. The exact path depends on which arguments are known at the call site, but the current implementation follows this order:

1. compile-time logging support decides whether the macro has an active logging path at all;
2. Logger::Condition() and the macro-side WouldLog precheck reject obvious disabled/inactive/level-filtered paths before normal formatting when possible;
3. Logger::DoLog() applies override frequency/repetition limits, subsystem allow/block policy, channel lookup, and output-availability checks;
4. after message formatting (and collapse processing when used), Channel::Display() applies channel state, re-entry protection, the display filter, subsystem/channel level filtering, link routing, and backend delivery;
5. Error/Critical records may also be copied to the configured error channel after delivery to the original channel.

The precheck is intentionally conservative. For example, when a thread-local subsystem or an error channel could change the final decision, it may allow the call to continue so the full runtime path can decide correctly.

Channel display filter

Each channel can install a callback with:

channel->SetDisplayFilter(...);

The callback type is:

std::function<bool(Context&, const char*)>

It receives the current Context and message text. Returning false drops the record for that channel before link/backend delivery.

The current Channel::Display() implementation releases Channel::DataLock before invoking the callback and reacquires it only if the callback accepts the record. This avoids running arbitrary application callback code while holding the channel data lock.

A display filter runs later than the global Condition() callback. Use Condition() for a cheap application-wide gate and SetDisplayFilter() when a decision needs channel-specific context or the formatted message.

---

Override-Based Filtering (Rate / Count Limiting)

In addition to the global condition callback, logme supports dropping messages based on override rules.

Overrides can be used to:

• Limit how often a message is allowed to appear (rate limiting)
• Limit how many times a message is allowed to appear (count limiting)

If an override limit is exceeded, the message is discarded before formatting, routing, or delivery to any backend, including file backends.

Example: One-time message

The OneTime example demonstrates that even if the application attempts to log the same message 1000 times, it will appear only once when an override like LOGME_ONCE4THIS is used:

LogmeW(LOGME_ONCE4THIS, "something went wrong!!!");

---

Performance Notes

• When logging is disabled at build time, the cost of logging calls (including filtering callbacks) is eliminated.
• When enabled (including Release builds via LOGME_INRELEASE), the pipeline is designed to filter messages as early as possible to keep overhead low.