Logger system API

Logger API

group log_api

Logger API.

Defines

LOG_LEVEL_NONE
LOG_LEVEL_ERR
LOG_LEVEL_WRN
LOG_LEVEL_INF
LOG_LEVEL_DBG
LOG_ERR(...)

Writes an ERROR level message to the log.

It’s meant to report severe errors, such as those from which it’s not possible to recover.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_WRN(...)

Writes a WARNING level message to the log.

It’s meant to register messages related to unusual situations that are not necessarily errors.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_INF(...)

Writes an INFO level message to the log.

It’s meant to write generic user oriented messages.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_DBG(...)

Writes a DEBUG level message to the log.

It’s meant to write developer oriented information.

Parameters
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_INST_ERR(_log_inst, ...)

Writes an ERROR level message associated with the instance to the log.

Message is associated with specific instance of the module which has independent filtering settings (if runtime filtering is enabled) and message prefix (<module_name>.<instance_name>). It’s meant to report severe errors, such as those from which it’s not possible to recover.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_INST_WRN(_log_inst, ...)

Writes a WARNING level message associated with the instance to the log.

Message is associated with specific instance of the module which has independent filtering settings (if runtime filtering is enabled) and message prefix (<module_name>.<instance_name>). It’s meant to register messages related to unusual situations that are not necessarily errors.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_INST_INF(_log_inst, ...)

Writes an INFO level message associated with the instance to the log.

Message is associated with specific instance of the module which has independent filtering settings (if runtime filtering is enabled) and message prefix (<module_name>.<instance_name>). It’s meant to write generic user oriented messages.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_INST_DBG(_log_inst, ...)

Writes a DEBUG level message associated with the instance to the log.

Message is associated with specific instance of the module which has independent filtering settings (if runtime filtering is enabled) and message prefix (<module_name>.<instance_name>). It’s meant to write developer oriented information.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • ...: A string optionally containing printk valid conversion specifier, followed by as many values as specifiers.

LOG_HEXDUMP_ERR(_data, _length, _str)

Writes an ERROR level hexdump message to the log.

It’s meant to report severe errors, such as those from which it’s not possible to recover.

Parameters
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_HEXDUMP_WRN(_data, _length, _str)

Writes a WARNING level message to the log.

It’s meant to register messages related to unusual situations that are not necessarily errors.

Parameters
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_HEXDUMP_INF(_data, _length, _str)

Writes an INFO level message to the log.

It’s meant to write generic user oriented messages.

Parameters
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_HEXDUMP_DBG(_data, _length, _str)

Writes a DEBUG level message to the log.

It’s meant to write developer oriented information.

Parameters
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_INST_HEXDUMP_ERR(_log_inst, _data, _length, _str)

Writes an ERROR hexdump message associated with the instance to the log.

Message is associated with specific instance of the module which has independent filtering settings (if runtime filtering is enabled) and message prefix (<module_name>.<instance_name>). It’s meant to report severe errors, such as those from which it’s not possible to recover.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_INST_HEXDUMP_WRN(_log_inst, _data, _length, _str)

Writes a WARNING level hexdump message associated with the instance to the log.

It’s meant to register messages related to unusual situations that are not necessarily errors.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_INST_HEXDUMP_INF(_log_inst, _data, _length, _str)

Writes an INFO level hexdump message associated with the instance to the log.

It’s meant to write generic user oriented messages.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_INST_HEXDUMP_DBG(_log_inst, _data, _length, _str)

Writes a DEBUG level hexdump message associated with the instance to the log.

It’s meant to write developer oriented information.

Parameters
  • _log_inst: Pointer to the log structure associated with the instance.
  • _data: Pointer to the data to be logged.
  • _length: Length of data (in bytes).
  • _str: Persistent, raw string.

LOG_MODULE_REGISTER(...)

Create module-specific state and register the module with Logger.

This macro normally must be used after including <logging/log.h> to complete the initialization of the module.

Module registration can be skipped in two cases:

  • The module consists of more than one file, and another file invokes this macro. (LOG_MODULE_DECLARE() should be used instead in all of the module’s other files.)
  • Instance logging is used and there is no need to create module entry. In that case LOG_LEVEL_SET() should be used to set log level used within the file.

Macro accepts one or two parameters:

  • module name
  • optional log level. If not provided then default log level is used in the file.

Example usage:

  • LOG_MODULE_REGISTER(foo, CONFIG_FOO_LOG_LEVEL)
  • LOG_MODULE_REGISTER(foo)

Note
The module’s state is defined, and the module is registered, only if LOG_LEVEL for the current source file is non-zero or it is not defined and CONFIG_LOG_DEFAULT_LOG_LEVEL is non-zero. In other cases, this macro has no effect.
See
LOG_MODULE_DECLARE

LOG_MODULE_DECLARE(...)

Macro for declaring a log module (not registering it).

Modules which are split up over multiple files must have exactly one file use LOG_MODULE_REGISTER() to create module-specific state and register the module with the logger core.

The other files in the module should use this macro instead to declare that same state. (Otherwise, LOG_INF() etc. will not be able to refer to module-specific state variables.)

Macro accepts one or two parameters:

  • module name
  • optional log level. If not provided then default log level is used in the file.

Example usage:

  • LOG_MODULE_DECLARE(foo, CONFIG_FOO_LOG_LEVEL)
  • LOG_MODULE_DECLARE(foo)

Note
The module’s state is declared only if LOG_LEVEL for the current source file is non-zero or it is not defined and CONFIG_LOG_DEFAULT_LOG_LEVEL is non-zero. In other cases, this macro has no effect.
See
LOG_MODULE_REGISTER

LOG_LEVEL_SET(level)

Macro for setting log level in the file or function where instance logging API is used.

Parameters
  • level: Level used in file or in function.

Functions

int log_printk(const char *fmt, va_list ap)

Writes an formatted string to the log.

Conditionally compiled (see CONFIG_LOG_PRINTK). Function provides printk functionality. It is inefficient compared to standard logging because string formatting is performed in the call context and not deferred to the log processing context (log_process).

return Number of bytes written.

Parameters
  • fmt: Formatted string to output.
  • ap: Variable parameters.

char *log_strdup(const char *str)

Copy transient string to a buffer from internal, logger pool.

Function should be used when transient string is intended to be logged. Logger allocates a buffer and copies input string returning a pointer to the copy. Logger ensures that buffer is freed when logger message is freed.

Return
Copy of the string or default string if buffer could not be allocated. String may be truncated if input string does not fit in a buffer from the pool (see CONFIG_LOG_STRDUP_MAX_STRING).
Parameters
  • str: Transient string.

Logger control

group log_ctrl

Logger control API.

Defines

LOG_INIT
LOG_PANIC
LOG_PROCESS

Typedefs

typedef u32_t (*timestamp_get_t)(void)

Functions

void log_core_init(void)

Function system initialization of the logger.

Function is called during start up to allow logging before user can explicitly initialize the logger.

void log_init(void)

Function for user initialization of the logger.

void log_thread_set(k_tid_t process_tid)

Function for providing thread which is processing logs.

See CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD.

Note
Function has asserts and has no effect when CONFIG_LOG_PROCESS is set.
Parameters
  • process_tid: Process thread id. Used to wake up the thread.

int log_set_timestamp_func(timestamp_get_t timestamp_getter, u32_t freq)

Function for providing timestamp function.

Return
0 on success or error.
Parameters
  • timestamp_getter: Timestamp function.
  • freq: Timestamping frequency.

void log_panic(void)

Switch the logger subsystem to the panic mode.

Returns immediately if the logger is already in the panic mode.

On panic the logger subsystem informs all backends about panic mode. Backends must switch to blocking mode or halt. All pending logs are flushed after switching to panic mode. In panic mode, all log messages must be processed in the context of the call.

bool log_process(bool bypass)

Process one pending log message.

Parameters
  • bypass: If true message is released without being processed.
Return Value
  • true: There is more messages pending to be processed.
  • false: No messages pending.

u32_t log_buffered_cnt(void)

Return number of buffered log messages.

Return
Number of currently buffered log messages.

u32_t log_src_cnt_get(u32_t domain_id)

Get number of independent logger sources (modules and instances)

Return
Number of sources.
Parameters
  • domain_id: Domain ID.

const char *log_source_name_get(u32_t domain_id, u32_t src_id)

Get name of the source (module or instance).

Return
Source name or NULL if invalid arguments.
Parameters
  • domain_id: Domain ID.
  • src_id: Source ID.

const char *log_domain_name_get(u32_t domain_id)

Get name of the domain.

Return
Domain name.
Parameters
  • domain_id: Domain ID.

u32_t log_filter_get(struct log_backend const *const backend, u32_t domain_id, u32_t src_id, bool runtime)

Get source filter for the provided backend.

Return
Severity level.
Parameters
  • backend: Backend instance.
  • domain_id: ID of the domain.
  • src_id: Source (module or instance) ID.
  • runtime: True for runtime filter or false for compiled in.

u32_t log_filter_set(struct log_backend const *const backend, u32_t domain_id, u32_t src_id, u32_t level)

Set filter on given source for the provided backend.

Return
Actual level set which may be limited by compiled level. If filter was set for all backends then maximal level that was set is returned.
Parameters
  • backend: Backend instance. NULL for all backends.
  • domain_id: ID of the domain.
  • src_id: Source (module or instance) ID.
  • level: Severity level.

void log_backend_enable(struct log_backend const *const backend, void *ctx, u32_t level)

Enable backend with initial maximum filtering level.

Parameters
  • backend: Backend instance.
  • ctx: User context.
  • level: Severity level.

void log_backend_disable(struct log_backend const *const backend)

Disable backend.

Parameters
  • backend: Backend instance.

Log message

group log_msg

Log message API.

Defines

LOG_MAX_NARGS

Maximum number of arguments in the standard log entry.

It is limited by 4 bit nargs field in the log message.

LOG_MSG_NARGS_SINGLE_CHUNK

Number of arguments in the log entry which fits in one chunk.

LOG_MSG_NARGS_HEAD_CHUNK

Number of arguments in the head of extended standard log message..

LOG_MSG_HEXDUMP_BYTES_SINGLE_CHUNK

Maximal amount of bytes in the hexdump entry which fits in one chunk.

LOG_MSG_HEXDUMP_BYTES_HEAD_CHUNK

Number of bytes in the first chunk of hexdump message if message consists of more than one chunk.

HEXDUMP_BYTES_CONT_MSG

Number of bytes that can be stored in chunks following head chunk in hexdump log message.

ARGS_CONT_MSG
LOG_MSG_TYPE_STD

Flag indicating standard log message.

LOG_MSG_TYPE_HEXDUMP

Flag indicating hexdump log message.

COMMON_PARAM_HDR

Common part of log message header.

LOG_MSG_HEXDUMP_LENGTH_BITS

Number of bits used for storing length of hexdump log message.

LOG_MSG_HEXDUMP_MAX_LENGTH

Maximum length of log hexdump message.

Functions

void log_msg_pool_init(void)

Function for initialization of the log message pool.

void log_msg_get(struct log_msg *msg)

Function for indicating that message is in use.

Message can be used (read) by multiple users. Internal reference counter is atomically increased. See log_msg_put.

Parameters
  • msg: Message.

void log_msg_put(struct log_msg *msg)

Function for indicating that message is no longer in use.

Internal reference counter is atomically decreased. If reference counter equals 0 message is freed.

Parameters
  • msg: Message.

static u32_t log_msg_domain_id_get(struct log_msg *msg)

Get domain ID of the message.

Return
Domain ID.
Parameters
  • msg: Message

static u32_t log_msg_source_id_get(struct log_msg *msg)

Get source ID (module or instance) of the message.

Return
Source ID.
Parameters
  • msg: Message

static u32_t log_msg_level_get(struct log_msg *msg)

Get severity level of the message.

Return
Severity message.
Parameters
  • msg: Message

static u32_t log_msg_timestamp_get(struct log_msg *msg)

Get timestamp of the message.

Return
Timestamp value.
Parameters
  • msg: Message

static bool log_msg_is_raw_string(struct log_msg *msg)

Check if message is a raw string (see CONFIG_LOG_PRINTK).

Parameters
  • msg: Message
Return Value
  • true: Message contains raw string.
  • false: Message does not contain raw string.

static bool log_msg_is_std(struct log_msg *msg)

Check if message is of standard type.

Parameters
  • msg: Message
Return Value
  • true: Standard message.
  • false: Hexdump message.

u32_t log_msg_nargs_get(struct log_msg *msg)

Returns number of arguments in standard log message.

Return
Number of arguments.
Parameters
  • msg: Standard log message.

u32_t log_msg_arg_get(struct log_msg *msg, u32_t arg_idx)

Gets argument from standard log message.

Return
Argument value or 0 if arg_idx exceeds number of arguments in the message.
Parameters
  • msg: Standard log message.
  • arg_idx: Argument index.

const char *log_msg_str_get(struct log_msg *msg)

Gets pointer to the unformatted string from standard log message.

Return
Pointer to the string.
Parameters
  • msg: Standard log message.

struct log_msg *log_msg_hexdump_create(const char *str, const u8_t *data, u32_t length)

Allocates chunks for hexdump message and copies the data.

Function resets header and sets following fields:

  • message type
  • length

Note
Allocation and partial filling is combined for performance reasons.
Return
Pointer to allocated head of the message or NULL
Parameters
  • str: String.
  • data: Data.
  • length: Data length.

void log_msg_hexdump_data_put(struct log_msg *msg, u8_t *data, size_t *length, size_t offset)

Put data into hexdump log message.

Parameters
  • msg: Message.
  • data: Data to be copied.
  • length: Input: requested amount. Output: actual amount.
  • offset: Offset.

void log_msg_hexdump_data_get(struct log_msg *msg, u8_t *data, size_t *length, size_t offset)

Get data from hexdump log message.

Parameters
  • msg: Message.
  • data: Buffer for data.
  • length: Input: requested amount. Output: actual amount.
  • offset: Offset.

union log_msg_chunk *log_msg_no_space_handle(void)
static union log_msg_chunk *log_msg_chunk_alloc(void)
static struct log_msg *log_msg_create_0(const char *str)

Create standard log message with no arguments.

Function resets header and sets following fields:

  • message type
  • string pointer

Return
Pointer to allocated head of the message or NULL.

static struct log_msg *log_msg_create_1(const char *str, u32_t arg1)

Create standard log message with one argument.

Function resets header and sets following fields:

  • message type
  • string pointer
  • number of arguments
  • argument

Return
Pointer to allocated head of the message or NULL.
Parameters
  • str: String.
  • arg1: Argument.

static struct log_msg *log_msg_create_2(const char *str, u32_t arg1, u32_t arg2)

Create standard log message with two arguments.

Function resets header and sets following fields:

  • message type
  • string pointer
  • number of arguments
  • arguments

Return
Pointer to allocated head of the message or NULL.
Parameters
  • str: String.
  • arg1: Argument 1.
  • arg2: Argument 2.

static struct log_msg *log_msg_create_3(const char *str, u32_t arg1, u32_t arg2, u32_t arg3)

Create standard log message with three arguments.

Function resets header and sets following fields:

  • message type
  • string pointer
  • number of arguments
  • arguments

Return
Pointer to allocated head of the message or NULL.
Parameters
  • str: String.
  • arg1: Argument 1.
  • arg2: Argument 2.
  • arg3: Argument 3.

struct log_msg *log_msg_create_n(const char *str, u32_t *args, u32_t nargs)

Create standard log message with variable number of arguments.

Function resets header and sets following fields:

  • message type
  • string pointer
  • number of arguments
  • arguments

Return
Pointer to allocated head of the message or NULL.
Parameters
  • str: String.
  • args: Array with arguments.
  • nargs: Number of arguments.

Variables

struct k_mem_slab log_msg_pool
struct log_msg_ids
#include <log_msg.h>

Part of log message header identifying source and level.

struct log_msg_generic_hdr
#include <log_msg.h>

Part of log message header common to standard and hexdump log message.

struct log_msg_std_hdr
#include <log_msg.h>

Part of log message header specific to standard log message.

struct log_msg_hexdump_hdr
#include <log_msg.h>

Part of log message header specific to hexdump log message.

struct log_msg_hdr
#include <log_msg.h>

Log message header structure

union log_msg_head_data
#include <log_msg.h>

Data part of log message.

Public Members

u32_t args[3]
u8_t bytes[(3 * sizeof(u32_t))]
struct log_msg_ext_head_data
#include <log_msg.h>

Data part of extended log message.

struct log_msg
#include <log_msg.h>

Log message structure.

struct log_msg_cont
#include <log_msg.h>

Chunks following message head when message is extended.

union log_msg_chunk
#include <log_msg.h>

Log message.

Public Members

struct log_msg head
struct log_msg_cont cont

Logger backend interface

group log_backend

Logger backend interface.

Defines

LOG_BACKEND_DEFINE(_name, _api, _autostart)

Macro for creating a logger backend instance.

Parameters
  • _name: Name of the backend instance.
  • _api: Logger backend API.
  • _autostart: If true backend is initialized and activated together with the logger subsystem.

Functions

static void log_backend_put(const struct log_backend *const backend, struct log_msg *msg)

Put message with log entry to the backend.

Parameters
  • backend: Pointer to the backend instance.
  • msg: Pointer to message with log entry.

static void log_backend_dropped(const struct log_backend *const backend, u32_t cnt)

Notify backend about dropped log messages.

Function is optional.

Parameters
  • backend: Pointer to the backend instance.
  • cnt: Number of dropped logs since last notification.

static void log_backend_panic(const struct log_backend *const backend)

Reconfigure backend to panic mode.

Parameters
  • backend: Pointer to the backend instance.

static void log_backend_id_set(const struct log_backend *const backend, u8_t id)

Set backend id.

Note
It is used internally by the logger.
Parameters
  • backend: Pointer to the backend instance.
  • id: ID.

static u8_t log_backend_id_get(const struct log_backend *const backend)

Get backend id.

Note
It is used internally by the logger.
Return
Id.
Parameters
  • backend: Pointer to the backend instance.

static const struct log_backend *log_backend_get(u32_t idx)

Get backend.

Return
Pointer to the backend instance.
Parameters
  • idx: Pointer to the backend instance.

static int log_backend_count_get(void)

Get number of backends.

Return
Number of backends.

static void log_backend_activate(const struct log_backend *const backend, void *ctx)

Activate backend.

Parameters
  • backend: Pointer to the backend instance.
  • ctx: User context.

static void log_backend_deactivate(const struct log_backend *const backend)

Deactivate backend.

Parameters
  • backend: Pointer to the backend instance.

static bool log_backend_is_active(const struct log_backend *const backend)

Check state of the backend.

Return
True if backend is active, false otherwise.
Parameters
  • backend: Pointer to the backend instance.

struct log_backend_api
#include <log_backend.h>

Logger backend API.

struct log_backend_control_block
#include <log_backend.h>

Logger backend control block.

struct log_backend
#include <log_backend.h>

Logger backend structure.

Logger output formatting

group log_output

Log output API.

Defines

LOG_OUTPUT_FLAG_COLORS

Flag forcing ANSI escape code colors, red (errors), yellow (warnings).

LOG_OUTPUT_FLAG_TIMESTAMP

Flag forcing timestamp.

LOG_OUTPUT_FLAG_FORMAT_TIMESTAMP

Flag forcing timestamp formatting.

LOG_OUTPUT_FLAG_LEVEL

Flag forcing severity level prefix.

LOG_OUTPUT_FLAG_CRLF_NONE

Flag preventing the logger from adding CR and LF characters.

LOG_OUTPUT_FLAG_CRLF_LFONLY

Flag forcing a single LF character for line breaks.

LOG_OUTPUT_FLAG_FORMAT_SYSLOG

Flag forcing syslog format specified in RFC 5424.

LOG_OUTPUT_DEFINE(_name, _func, _buf, _size)

Create log_output instance.

Parameters
  • _name: Instance name.
  • _func: Function for processing output data.
  • _buf: Pointer to the output buffer.
  • _size: Size of the output buffer.

Typedefs

typedef int (*log_output_func_t)(u8_t *buf, size_t size, void *ctx)

Prototype of the function processing output data.

Return
Number of bytes processed.
Parameters
  • data: Data.
  • length: Data length.
  • ctx: User context.

Functions

void log_output_msg_process(const struct log_output *log_output, struct log_msg *msg, u32_t flags)

Process log messages to readable strings.

Function is using provided context with the buffer and output function to process formatted string and output the data.

Parameters
  • log_output: Pointer to the log output instance.
  • msg: Log message.
  • flags: Optional flags.

void log_output_dropped_process(const struct log_output *log_output, u32_t cnt)

Process dropped messages indication.

Function prints error message indicating lost log messages.

Parameters
  • log_output: Pointer to the log output instance.
  • cnt: Number of dropped messages.

void log_output_flush(const struct log_output *log_output)

Flush output buffer.

Parameters

static void log_output_ctx_set(const struct log_output *log_output, void *ctx)

Function for setting user context passed to the output function.

Parameters
  • log_output: Pointer to the log output instance.
  • ctx: User context.

static void log_output_hostname_set(const struct log_output *log_output, const char *hostname)

Function for setting hostname of this device.

Parameters
  • log_output: Pointer to the log output instance.
  • hostname: Hostname of this device

void log_output_timestamp_freq_set(u32_t freq)

Set timestamp frequency.

Parameters
  • freq: Frequency in Hz.

struct log_output
#include <log_output.h>

Log_output instance structure.