4.10. Configuring and Using the Logger

4.10.1. Overview

Anjay Lite provides a lightweight logging system designed for embedded environments. It is used internally by Anjay Lite itself and is also available for end user applications. This allows you to wiev both the library’s diagnostic messages and your application logs in a consistent format, while keeping runtime and code size overhead low.

4.10.2. Logger types

Exactly one logger type must be enabled:

  • Built-in handler (ANJ_LOG_FULL)

    The library provides its own implementation. Log lines are formatted into a buffer, prefixed with log level, module, file and line number, and then passed to an output function.

  • Alternate handler (ANJ_LOG_ALT_IMPL_HEADER)

    A user-provided header file defines how anj_log() expands. This mode is meant for integrating Anjay Lite with platform loggers such as Zephyr’s logging API or other RTOS-specific systems. It requires more user setup but offers maximum flexibility and tight integration with existing logging frameworks.

4.10.3. Output backends for the built-in handler

When using the built-in handler (ANJ_LOG_FULL), you must select exactly one output type:

  • stderr output (ANJ_LOG_HANDLER_OUTPUT_STDERR)

    The library provides a default anj_log_handler_output() implementation that writes the formatted log line to stderr.

  • custom output (ANJ_LOG_HANDLER_OUTPUT_ALT)

    The user must implement anj_log_handler_output(const char *output, size_t len). This function receives the fully formatted log line and is responsible for transmitting it to the desired backend. This option is recommended for embedded systems, as it allows routing logs to UART, RTT, or any other interface available on the platform.

Example: minimal UART output implementation for STM32 HAL:

#include <anj/compat/log_impl_decls.h>
#include <stm32u3xx_nucleo.h>

void anj_log_handler_output(const char *output, size_t len) {
    HAL_UART_Transmit(&hcom_uart[COM1], (const uint8_t *) output,
                      len, COM_POLL_TIMEOUT);
    static const char newline[] = "\r\n";
    HAL_UART_Transmit(&hcom_uart[COM1], (const uint8_t *) newline,
                      sizeof(newline) - 1, COM_POLL_TIMEOUT);
}

4.10.4. Alternate handler

If ANJ_LOG_ALT_IMPL_HEADER is defined, the built-in implementation is disabled. The provided header file must define the macro ANJ_LOG_HANDLER_IMPL_MACRO(Module, LogLevel, ...). All anj_log() calls expand through this macro.

This approach is useful when you want to integrate Anjay Lite logging with existing platform loggers that are also macro-based, such as Zephyr LOG_*(). Although this requires additional setup, it allows complete alignment with the target system’s logging conventions, filtering, and runtime control.

4.10.5. Usage

Emit a log statement using the anj_log macro:

anj_log(my_module, L_INFO, "Hello %s (%d)", "world", 42);

To reduce binary size, you can wrap constant parts of log strings with ANJ_LOG_DISPOSABLE(). If ANJ_LOG_STRIP_CONSTANTS is enabled, these constants are replaced with a single space during compilation:

anj_log(my_module, L_DEBUG, ANJ_LOG_DISPOSABLE("Result: ") "%d", result);

4.10.6. Modules

Log statements in Anjay Lite are grouped by modules, e.g. bootstrap, exchange, observe. When writing your own logs you can also choose a module name. This mechanism serves two purposes:

  • Debugging convenience - you can enable detailed logs only for specific modules during troubleshooting.

  • Footprint control - increasing the log level for a single module does not increase binary size as much as enabling verbose logs globally.

4.10.7. Filtering log levels

Log levels form a hierarchy:

  • L_TRACE - enables all messages

  • L_DEBUG - enables debug, info, warning, and error messages

  • L_INFO - enables info, warning, and error messages

  • L_WARNING - enables warnings and errors

  • L_ERROR - enables only errors

  • L_MUTED - disables logging completely

The default log level is controlled by ANJ_LOG_LEVEL_DEFAULT (defaults to L_INFO if not set). Logs below this level are removed at compile time.

For finer control, per-module overrides are possible via ANJ_LOG_FILTERING_CONFIG_HEADER, which shall point to a user-provided header file with per-module settings. For example:

// in my_log_filtering_config.h
#define ANJ_LOG_LEVEL_FOR_MODULE_exchange L_TRACE
#define ANJ_LOG_LEVEL_FOR_MODULE_observe L_MUTED

This configuration enables trace logs for the exchange module while completely disabling logs in observe. Such selective configuration makes it possible to diagnose specific problems while keeping the binary size low.