pw_log

Overview

Robust and portable logging for embedded projects.

Main docs: Home | The pw_log protobuf | Tokenized log arguments | Backends

Submodules
	Global config
	Google Logging (glog) macros
	Module config
	Protobuf helpers
	Short macros
	Optional shortened versions of the PW_LOG macros.
	Tokenized args

Macros
#define	PW_LOG_LEVEL_DEBUG   1
#define	PW_LOG_LEVEL_INFO   2
#define	PW_LOG_LEVEL_WARN   3
#define	PW_LOG_LEVEL_ERROR   4
#define	PW_LOG_LEVEL_CRITICAL   5
#define	PW_LOG_LEVEL_FATAL   7
#define	PW_LOG_LEVEL_BITS   3
	Number of bits required to represent the log level.
#define	PW_LOG_LEVEL_BITMASK   7
#define	PW_LOG( level, verbosity, module, flags, ...)
#define	PW_LOG_FLAG_BITS   2
#define	PW_LOG_EVERY_N_DURATION(level, min_interval_between_logs, msg, ...)

Macro Definition Documentation

PW_LOG

#define PW_LOG	(		level,
			verbosity,
			module,
			flags,
			...
	)

Value:

  do {                                                                     \
    if (PW_LOG_ENABLE_IF(level, verbosity, module, flags)) {               \
      PW_HANDLE_LOG(level, module, flags, __VA_ARGS__);                    \
    }                                                                      \
  } while (0)

Accepts the format string and its arguments in a variadic macro. The format string is not listed as a separate argument to avoid adding a comma after the format string when it has no arguments.

PW_LOG_EVERY_N_DURATION

#define PW_LOG_EVERY_N_DURATION	(		level,
			min_interval_between_logs,
			msg,
			...
	)

Value:

  do {                                                                      \
    static pw::log::internal::RateLimiter rate_limiter;                     \
                                                                            \
    if (auto result = rate_limiter.Poll(min_interval_between_logs);         \
        result.count == std::numeric_limits<uint16_t>::max()) {             \
      PW_LOG(level,                                                         \
             PW_LOG_LEVEL,                                                  \
             PW_LOG_MODULE_NAME,                                            \
             PW_LOG_FLAGS,                                                  \
             msg " (skipped %d or more, %d/s)",                             \
             ##__VA_ARGS__,                                                 \
             static_cast<unsigned>(result.count),                           \
             static_cast<unsigned>(result.logs_per_s));                     \
    } else if (result.count != 0) {                                         \
      PW_LOG(level,                                                         \
             PW_LOG_LEVEL,                                                  \
             PW_LOG_MODULE_NAME,                                            \
             PW_LOG_FLAGS,                                                  \
             msg " (skipped %d, %d/s)",                                     \
             ##__VA_ARGS__,                                                 \
             static_cast<unsigned>(result.count - 1),                       \
             static_cast<unsigned>(result.logs_per_s));                     \
    }                                                                       \
  } while (0)

Logs a message at the given level, only if it hasn't been logged within min_interval_between_logs.

Parameters

level	An integer level as defined by pw_log/levels.h
min_interval_between_logs	A pw::chrono::SystemClock::duration that defines the minimum time interval between unsuppressed logs
msg	Formattable message, same as you would use for PW_LOG or variants

Includes a summary of how many logs were skipped, and a rough rate in integer seconds.

Warning

This macro is NOT thread-safe. The underlying object being modified by multiple threads calling the macro context may result in undefined behavior.

Intended to supplement and replace widespread use of EVERY_N` for logging. The main benefit this provides is responsiveness for bursty logs. LOG_RATE_LIMITED will log as soon as a burst starts - provided the min_interval_between_logs has elapsed - while EVERY_N may sit idle for a full period depending on the count state.

Note that this will not log until called again, so the summary may include skipped logs from a prior burst.

PW_LOG_FLAG_BITS

#define PW_LOG_FLAG_BITS   2

Default: Number of bits available for the log flags

All log statements have a flags field, and this define is the number of bits available for the flags. Some backends restrict this for better efficiency. By default, pick a restricted but large enough value to work for most cases.

PW_LOG_LEVEL_DEBUG

#define PW_LOG_LEVEL_DEBUG   1

Standard log levels. Values are limited to 3 bits, to fit within the protobuf definition of LogEntry's line_level in pw_log_rpc. These levels correspond with the log levels from Python's logging library, but have different values.