Overview

Robust and portable logging for embedded projects.

Submodules
	Global config

	Google Logging (glog) macros

	Module config

	Protobuf helpers

	Short macros
	Optional shortened versions of the `PW_LOG` macros.

	Tokenized args

	pw_log_string

	pw_log_tokenized

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.