Log Message Macros

Macros
#define	logStr(level, str)   _logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteAlways, 0, str)
#define	logStrC(level, chan, str)   _logStr_##level(LOG_##level, chan, LOG_SiteAlways, 0, str)
#define	logFmt(level, fmt, ...)   _logFmtArgs(level, LOG_CHANNEL, LOG_SiteAlways, 0, fmt, __VA_ARGS__)
#define	logFmtC(level, chan, fmt, ...)   _logFmtArgs(level, chan, LOG_SiteAlways, 0, fmt, __VA_ARGS__)

Detailed Description

These macros provide the primary interface for logging messages. They compile to no-ops for levels that are disabled based on DEBUG_LEVEL, ensuring zero overhead for disabled log levels.

Debug Level Filtering:

• DEBUG_LEVEL >= 2: All levels including Trace
• DEBUG_LEVEL >= 1: Debug and above (no Trace)
• DEBUG_LEVEL == 0: Diag and above (no Debug or Trace)

Dev variants: The Dev prefix variants (e.g., logStr(DevInfo, ...)) are only compiled in development builds and map to their corresponding regular levels in production.

Binding a source file to a channel: logStr and logFmt log to whatever LOG_CHANNEL names, which is the default channel unless the file says otherwise. A translation unit declares its channel once, near the top, and every call site in the file picks it up with no logger object carried anywhere:

#include <cx/log.h>
 
#undef LOG_CHANNEL
#define LOG_CHANNEL chan_net_http    // a LogChannel* from logChan()

The #undef is needed because log.h supplies the default. Use logStrC()/logFmtC() where the channel is chosen at runtime rather than per file.

These macros are statements, not expressions. Each opens a block holding the call site's LogSite (see Rate-Limited Log Macros), so a log call cannot appear where an expression is required – as the operand of ?:, for instance. That form fails to compile rather than misbehaving.

Macro Definition Documentation

logFmt

#define logFmt	(		level,
			fmt,
			...
	)		_logFmtArgs(level, LOG_CHANNEL, LOG_SiteAlways, 0, fmt, __VA_ARGS__)

void logFmt(level, fmt, ...)

Log a formatted message using the file's channel (LOG_CHANNEL, default if unset)

Parameters

level	Log level without LOG_ prefix (e.g., Info, Warn, Error)
fmt	Format string (see Formatting for format syntax)
...	Format arguments wrapped in stvar(); at least one is required

A template may also name context fields by key (see Log Context). Such a template needs no arguments of its own, but the macro still needs one: pass stvNone, which the formatter never matches and a structured destination never emits.

logFmt(Info, _SL("Connection from ${string}:${int}"),
       stvar(string, hostname), stvar(int32, port));
logFmt(Warn, _SL("Invalid value: ${int}"), stvar(int32, value));
logFmt(Info, _SL("handling ${string:reqid}"), stvNone);   // reqid comes from the context

Definition at line 643 of file log.h.

logFmtC

#define logFmtC	(		level,
			chan,
			fmt,
			...
	)		_logFmtArgs(level, chan, LOG_SiteAlways, 0, fmt, __VA_ARGS__)

void logFmtC(level, chan, fmt, ...)

Log a formatted message with a specific channel

Parameters

level	Log level without LOG_ prefix
chan	LogChannel pointer
fmt	Format string
...	Format arguments wrapped in stvar() LogChannel *dbchan = logChan(_SL("db")); logFmtC(Warn, dbchan, _SL("Query took ${int}ms"), stvar(int32, elapsed));

Definition at line 656 of file log.h.

logStr

#define logStr	(		level,
			str
	)		_logStr_##level(LOG_##level, LOG_CHANNEL, LOG_SiteAlways, 0, str)

void logStr(level, str)

Log a string message using the file's channel (LOG_CHANNEL, default if unset)

Parameters

level	Log level without LOG_ prefix (e.g., Info, Warn, Error)
str	String or string reference to log logStr(Info, _SL("Application started")); logStr(Error, errorMessage);

Definition at line 612 of file log.h.

logStrC

#define logStrC	(		level,
			chan,
			str
	)		_logStr_##level(LOG_##level, chan, LOG_SiteAlways, 0, str)

void logStrC(level, chan, str)

Log a string message with a specific channel

Parameters

level	Log level without LOG_ prefix (e.g., Info, Warn, Error)
chan	LogChannel pointer
str	String or string reference to log LogChannel *netchan = logChan(_SL("net/http")); logStrC(Info, netchan, _SL("Connection established"));

Definition at line 624 of file log.h.