Logging

Lightweight, level-based logging facility.

Each translation unit that wants to log declares a module name once via LOG_MODULE; afterwards the LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERROR and LOG_SEVERE macros emit messages tagged with that module name and a timestamp. The runtime threshold is set with cw_set_loglevel — messages above it are discarded at near-zero cost.

Example

cpp

#include <logging.h>

LOG_MODULE(sensor)   // module tag for this file

void sensor_read(int channel) {
    LOG_DEBUG("reading ch=%d", channel);
    if (channel < 0) {
        LOG_ERROR("invalid channel %d", channel);
        return;
    }
    LOG_INFO("sensor ready");
}

int main(void) {
    cw_set_loglevel(CW_LOGLVL_INFO);  // suppress DEBUG
    sensor_read(3);
}

The functions below are output primitives used by the LOG_* macros. Application code normally does not call them directly.

Functions Overview

	Name
void	cw_log_output(const char * fmt, ... ) Writes a formatted log message to the active log sink.
void	cw_log_prepare_formatting(int lvl) Prepares the log backend for emitting a message at the given level.
void	cw_log_prefix(int lvl, const char * mod) Emits the log line prefix (level + module name).
void	cw_log_cleanup(int nl) Closes the current log line.
void	cw_log_timestamp(void ) Emits a timestamp prefix for the current log line.
void	cw_set_loglevel(int lvl) Sets the global runtime log threshold.

Defines

Name
LOG_MODULE_ENABLED
CW_LOGLVL_SEVERE	Unrecoverable condition; the system cannot continue.
CW_LOGLVL_ERROR	Operation failed; the caller should react.
CW_LOGLVL_WARNING	Unexpected condition that did not break the operation.
CW_LOGLVL_INFO	High-level progress information.
CW_LOGLVL_DEBUG	Verbose details useful while debugging.
LOG_MODULE(x)	Declares the module tag prefixed to every log line in this file.
LOG_MODULE_REREG(x)	Re-assigns the module tag at runtime within the current scope.
LOG_DEBUG(...)	Logs a printf-formatted message at CW_LOGLVL_DEBUG.
LOG_INFO(...)	Logs a printf-formatted message at CW_LOGLVL_INFO.
LOG_WARNING(...)	Logs a printf-formatted message at CW_LOGLVL_WARNING.
LOG_ERROR(...)	Logs a printf-formatted message at CW_LOGLVL_ERROR.
LOG_SEVERE(...)	Logs a printf-formatted message at CW_LOGLVL_SEVERE.
CW_LOG_FORMATTED(lvl, ...)
CW_LOG_PREPARE(l)
CW_LOG_PREFIX(l, m)
CW_LOG_TIMESTAMP
CW_LOG_OUTP(...)
CW_LOG_CLEANUPN

Function Details

function cw_log_output

cpp

void cw_log_output(
    const char * fmt,
    ... 
)

Writes a formatted log message to the active log sink.

Parameters:

fmt printf-style format string.
... Values matching the format specifiers in fmt.

function cw_log_prepare_formatting

cpp

void cw_log_prepare_formatting(
    int lvl
)

Prepares the log backend for emitting a message at the given level.

Parameters:

lvl One of CW_LOGLVL_SEVERE, CW_LOGLVL_ERROR, CW_LOGLVL_WARNING, CW_LOGLVL_INFO, CW_LOGLVL_DEBUG.

Called by the LOG_* macros before any output primitives so that the sink can, e.g., acquire a lock or set up coloring.

function cw_log_prefix

cpp

void cw_log_prefix(
    int lvl,
    const char * mod
)

Emits the log line prefix (level + module name).

Parameters:

lvl Log level constant.
mod Null-terminated module name registered with LOG_MODULE.

function cw_log_cleanup

cpp

void cw_log_cleanup(
    int nl
)

Closes the current log line.

Parameters:

nl If non-zero, a trailing newline is written.

function cw_log_timestamp

cpp

void cw_log_timestamp(
    void 
)

Emits a timestamp prefix for the current log line.

function cw_set_loglevel

cpp

void cw_set_loglevel(
    int lvl
)

Sets the global runtime log threshold.

Parameters:

lvl One of the CW_LOGLVL_* constants.

Messages with a level numerically higher than lvl are suppressed. For example, cw_set_loglevel(CW_LOGLVL_WARNING) lets through SEVERE, ERROR and WARNING but discards INFO and DEBUG.

Macros Documentation

define LOG_MODULE_ENABLED

cpp

#define LOG_MODULE_ENABLED 0

define CW_LOGLVL_SEVERE

cpp

#define CW_LOGLVL_SEVERE (0)

Unrecoverable condition; the system cannot continue.

define CW_LOGLVL_ERROR

cpp

#define CW_LOGLVL_ERROR (1)

Operation failed; the caller should react.

define CW_LOGLVL_WARNING

cpp

#define CW_LOGLVL_WARNING (2)

Unexpected condition that did not break the operation.

define CW_LOGLVL_INFO

cpp

#define CW_LOGLVL_INFO (3)

High-level progress information.

define CW_LOGLVL_DEBUG

cpp

#define CW_LOGLVL_DEBUG (4)

Verbose details useful while debugging.

define LOG_MODULE

cpp

#define LOG_MODULE(
    x
)

Declares the module tag prefixed to every log line in this file.

Parameters:

x Module name, e.g. [LOG_MODULE(uart_driver)](/embed/2.2.0/API//group__core__logging.md#define-log-module).

Place once at file scope (outside any function). The argument is taken verbatim (no quotes) and stringified internally.

define LOG_MODULE_REREG

cpp

#define LOG_MODULE_REREG(
    x
)

Re-assigns the module tag at runtime within the current scope.

Parameters:

x New module name (unquoted).

define LOG_DEBUG

cpp

#define LOG_DEBUG(
    ...
)
CW_LOG_FORMATTED(CW_LOGLVL_DEBUG, __VA_ARGS__)

Logs a printf-formatted message at CW_LOGLVL_DEBUG.

define LOG_INFO

cpp

#define LOG_INFO(
    ...
)
CW_LOG_FORMATTED(CW_LOGLVL_INFO, __VA_ARGS__)

Logs a printf-formatted message at CW_LOGLVL_INFO.

define LOG_WARNING

cpp

#define LOG_WARNING(
    ...
)
CW_LOG_FORMATTED(CW_LOGLVL_WARNING, __VA_ARGS__)

Logs a printf-formatted message at CW_LOGLVL_WARNING.

define LOG_ERROR

cpp

#define LOG_ERROR(
    ...
)
CW_LOG_FORMATTED(CW_LOGLVL_ERROR, __VA_ARGS__)

Logs a printf-formatted message at CW_LOGLVL_ERROR.

define LOG_SEVERE

cpp

#define LOG_SEVERE(
    ...
)
CW_LOG_FORMATTED(CW_LOGLVL_SEVERE, __VA_ARGS__)

Logs a printf-formatted message at CW_LOGLVL_SEVERE.

define CW_LOG_FORMATTED

cpp

#define CW_LOG_FORMATTED(
    lvl,
    ...
)

define CW_LOG_PREPARE

cpp

#define CW_LOG_PREPARE(
    l
)

define CW_LOG_PREFIX

cpp

#define CW_LOG_PREFIX(
    l,
    m
)

define CW_LOG_TIMESTAMP

cpp

#define CW_LOG_TIMESTAMP

define CW_LOG_OUTP

cpp

#define CW_LOG_OUTP(
    ...
)

define CW_LOG_CLEANUPN

cpp

#define CW_LOG_CLEANUPN

Logging ​

Example ​

Functions Overview ​

Defines ​

Function Details ​

function cw_log_output ​

function cw_log_prepare_formatting ​

function cw_log_prefix ​

function cw_log_cleanup ​

function cw_log_timestamp ​

function cw_set_loglevel ​

Macros Documentation ​

define LOG_MODULE_ENABLED ​

define CW_LOGLVL_SEVERE ​

define CW_LOGLVL_ERROR ​

define CW_LOGLVL_WARNING ​

define CW_LOGLVL_INFO ​

define CW_LOGLVL_DEBUG ​

define LOG_MODULE ​

define LOG_MODULE_REREG ​

define LOG_DEBUG ​

define LOG_INFO ​

define LOG_WARNING ​

define LOG_ERROR ​

define LOG_SEVERE ​

define CW_LOG_FORMATTED ​

define CW_LOG_PREPARE ​

define CW_LOG_PREFIX ​

define CW_LOG_TIMESTAMP ​

define CW_LOG_OUTP ​

define CW_LOG_CLEANUPN ​

Logging

Example

Functions Overview

Defines

Function Details

function cw_log_output

function cw_log_prepare_formatting

function cw_log_prefix

function cw_log_cleanup

function cw_log_timestamp

function cw_set_loglevel

Macros Documentation

define LOG_MODULE_ENABLED

define CW_LOGLVL_SEVERE

define CW_LOGLVL_ERROR

define CW_LOGLVL_WARNING

define CW_LOGLVL_INFO

define CW_LOGLVL_DEBUG

define LOG_MODULE

define LOG_MODULE_REREG

define LOG_DEBUG

define LOG_INFO

define LOG_WARNING

define LOG_ERROR

define LOG_SEVERE

define CW_LOG_FORMATTED

define CW_LOG_PREPARE

define CW_LOG_PREFIX

define CW_LOG_TIMESTAMP

define CW_LOG_OUTP

define CW_LOG_CLEANUPN