Feature Map

Feature Map

This page maps common logging-library terms to the way the same capability is implemented in logme.

The goal is discoverability. Some logme features intentionally live at a different layer than similarly named features in other libraries. For example, logme does not need a NullBackend to represent discarded output, and repetition control is not implemented as a backend-side duplicate filter.

---

Quick map

Common capability	logme mechanism	Main code areas	Related pages
Null sink / null backend	A channel with no backends, combined with early precheck	Channel, Precheck, logging macros	Why logme is fast, Precheck example
Sink-level filtering	Channel-level level/filter checks by design	Channel, Routing, OutputFlags	Core Concepts, Routing, Message Filtering
Duplicate suppression	_Once macros and override repetition limits	Logme.h, Override.h, Override.cpp	Override Scopes, OneTime example
Repeated-message aggregation	_Collapse, _CollapseEvery, _CollapseIgnore, and _CollapseIgnoreEvery macros	Logme.h, Context.h, Context.cpp, Logger.cpp	Collapse Logging
Rate-limited logging	_Every(ms) macros and override frequency limits	Logme.h, Override.h, Override.cpp	Advanced Features, OnceEvery example
Rotating file sink	FileBackend lifecycle policy: size rotation, time rotation, archive naming, retention, compression, and counters	FileBackend, FileBackendConfig, FileArchivePolicy, FileTimeRotationPolicy, RetentionCleaner, CompressionManager	File Backend, File Rotation & Retention
Total log directory size control	DirectorySizeWatchdog on the logger home directory	DirectorySizeWatchdog, Logger	File Rotation & Retention, Configuration JSON
Runtime backend management	Control API commands, logmectl, and logmeweb	Control/Command, logmectl, logmeweb	Runtime Control, Control Server, logmectl, logmeweb
Startup environment overrides	Explicit ApplyEnvironmentControl() call that reads LOGME_CONTROL* and runs policy-checked control commands	EnvironmentControl, ControlPolicy, Logger::Control(command, policy)	Environment Control, Control Policies
Custom sink / appender	Derive from Logme::Backend and implement Display(Context&), or use CallbackBackend for a function-based sink	Backend.h, CallbackBackend	Custom Backends, Backends
Structured sink output	Channel output flags select text, JSON, or XML rendering	OutputFlags, Context, format code	Structured Logging, OutputFlags
Recent-history capture / backtrace-style log history	RingBufferBackend	RingBufferBackend	Ring Buffer Backend, Recent-History Capture
Windows Event Log output	WindowsEventLogBackend	WindowsEventLogBackend, WindowsEventLogManager	Backends, Configuration JSON
Temporary in-memory output	BufferBackend	BufferBackend	Buffer Backend
Production dormant trace sites	Trace points	TracePoint, trace macros, control commands	Trace Points, TracePoints example
glog LOG / CHECK migration	Optional compatibility header	Logme/GlogCompat.h, Logme/Check.h	glog Compatibility, Fatal Handling
Fatal log + abort policy	LogmeC plus configurable fatal handler	Logger::SetFatalHandler, Logger::FlushAll	Fatal Handling
Crash logging / signal-handler marker	Separate emergency path outside channels and backends	Logme/CrashLog.h, Logger::OpenCrashLog, LogmeCrash, LogmeCrashRaw	Crash Logging
Count-based first/every macros	LogmeX_FirstN, LogmeX_EveryN	Logme/Check.h, Logme.h	Logging Macros, glog Compatibility

---

Implemented differently on purpose

No separate NullBackend

logme does not need a dedicated null backend. If a channel has no backends and no active routes that can receive the record, the logging path can reject the message early. That is cheaper and simpler than constructing a backend object whose only job is to discard records.

This is especially important for benchmark and production scenarios where logging calls remain compiled in, but no output is currently requested.

Channel-level filtering instead of backend-level routing

In logme, a channel is the unit of logging policy. The channel has its level, flags, routing links, subsystem policy, and backend list.

This is intentional. Fast rejection happens before formatting and before backend delivery. Adding per-backend level routing to the hot path would require checking backend policy during message acceptance and would weaken the channel-as-a-policy-unit model.

If different outputs need different policies, the logme model is to use separate channels or explicit routing, not hidden backend-level filters.

_Once and _Every instead of a duplicate-filter sink

Some libraries implement duplicate suppression as a sink wrapper. logme implements repetition and frequency control at the call site through _Once, _Every(ms), _Collapse, _CollapseEvery, _CollapseIgnore, _CollapseIgnoreEvery, and override helpers such as LOGME_ONCE4THIS, LOGME_EVERY4THIS, LOGME_ONCE4CALL, and LOGME_EVERY4CALL.

This keeps the decision close to the log statement and can reject repeated messages before formatting, routing, or backend delivery.

_Collapse, _CollapseEvery, and ignore variants for repeated-message aggregation

_Once and _Every either suppress or time-limit a call site without a repeat summary. _Collapse is different: it writes the first occurrence, suppresses repeated attempts with the same comparison key at that call site, and then writes a summary when the repeat count reaches the configured limit.

_CollapseEvery uses the same comparison model but emits the summary by time interval instead of by repeat count. This is useful when a repeated message can be emitted in a very tight loop.

_CollapseIgnore and _CollapseIgnoreEvery add regex-based normalization before comparison. This is useful for messages that differ only by volatile substrings such as request ids, timestamps, counters, or correlation ids.

This is intentionally a call-site feature rather than a backend duplicate filter, so repeated records can be stopped before backend delivery.

Environment control is explicit startup control

Some libraries provide environment variables such as LOG_LEVEL that are read automatically. logme does not do that. Environment variables become active only when the application calls ApplyEnvironmentControl().

The environment values contain normal control commands separated by ;. Those commands are checked by ControlPolicy before execution. This avoids creating a second configuration language and prevents untrusted environment variables from silently controlling the logger.

File rotation is part of FileBackend

logme does not expose file rotation as a separate sink type. The production file behavior is built into FileBackend and related file-management code.

The file backend supports size control, truncate-or-rotate behavior, hourly/daily/weekly/monthly time rotation, archive naming, startup index recovery, retention by file count/age/total size, optional gzip compression, append behavior, and lifecycle counters. The logger home directory can additionally be protected by DirectorySizeWatchdog, which limits total disk usage across matching files.

glog compatibility is an optional migration layer

logme provides a separate Logme/GlogCompat.h header for projects migrating from Google glog. It maps common glog-style macros such as LOG, CHECK, PLOG, DLOG, VLOG, LOG_FIRST_N, and LOG_EVERY_N to logme mechanisms.

The compatibility layer is not the preferred native model for new code. After migration, numeric VLOG(n) calls are usually better expressed as trace points, subsystem filters, or channels that can be controlled at runtime.

Fatal behavior is a policy

LogmeC writes a critical record. It does not abort by default. Applications that want glog-like LOG(FATAL) or CHECK behavior can install a fatal handler. Before the handler is called, logme runs FlushAll() to reduce the risk of losing buffered log data.

Crash logging is a separate emergency path

LogmeCrash and LogmeCrashRaw do not use channels, backends, runtime control, output flags, rotation, retention, C++ streams, std::format, or the async queue. They write directly to a prepared crash file, stderr, or stdout. This is intentionally separate from controlled fatal logging. Use it when the normal logging path is too risky to call from a crash or signal handler.

---

Remaining backend gaps

The following backend families are common in logging ecosystems but are not currently built-in logme backend types:

• SyslogBackend for Unix/Linux syslog integration
• SystemdJournalBackend for systemd services
• AndroidLogBackend / logcat backend for Android NDK projects
• optional network log streaming backend, if logme should provide native TCP/UDP/TLS log forwarding

CallbackBackend and WindowsEventLogBackend are now built-in backend types. They are backend additions, not replacements for the existing channel, filtering, override, runtime-control, or file-management model.