Logging library

Overview

Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using esp_log_level_set() function.

The log levels are Error, Warning, Info, Debug, and Verbose (from lowest to highest level of verbosity).

At compile time, filtering is done using CONFIG_LOG_DEFAULT_LEVEL option, set via menuconfig. All logging statements for levels higher than CONFIG_LOG_DEFAULT_LEVEL will be removed by the preprocessor.

At run time, all logs below CONFIG_LOG_DEFAULT_LEVEL are enabled by default. esp_log_level_set() function may be used to reduce logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.

Note that esp_log_level_set() can not increase logging level beyound that set by CONFIG_LOG_DEFAULT_LEVEL. To increase log level for a specific file at compile time, LOG_LOCAL_LEVEL macro can be used (see below for details).

How to use this library

In each C file which uses logging functionality, define TAG variable like this:

static const char* TAG = "MyModule";

then use one of logging macros to produce output, e.g:

ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);

Several macros are available for different verbosity levels:

  • ESP_LOGE - error (lowest)

  • ESP_LOGW - warning

  • ESP_LOGI - info

  • ESP_LOGD - debug

  • ESP_LOGV - verbose (highest)

Additionally there is an _EARLY variant for each of these macros (e.g. ESP_EARLY_LOGE). These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ESP_LOGx macros fall back to the same implementation as ESP_EARLY_LOGx macros. So the only place where ESP_EARLY_LOGx have to be used explicitly is the early startup code, such as heap allocator initialization code.

To override default verbosity level at file or component scope, define LOG_LOCAL_LEVEL macro. At file scope, define it before including esp_log.h, e.g.:

#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
#include "esp_log.h"

At component scope, define it in component makefile:

CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG

To configure logging output per module at runtime, add calls to esp_log_level_set() function:

esp_log_level_set("*", ESP_LOG_ERROR);        // set all components to ERROR level
esp_log_level_set("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
esp_log_level_set("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client

Logging to Host via JTAG

By default logging library uses vprintf-like function to write formatted output to dedicated UART. By calling a simple API, all log output may be routed to JTAG instead, making logging several times faster. For details please refer to section Logging to Host.

Application Example

Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check examples folder of espressif/esp-idf repository, that among others, contains the following examples:

API Reference

Functions

void esp_log_level_set(const char *tag, esp_log_level_t level)

Set log level for given tag.

If logging for given component has already been enabled, changes previous setting.

Note that this function can not raise log level above the level set using CONFIG_LOG_DEFAULT_LEVEL setting in menuconfig.

To raise log level above the default one for a given file, define LOG_LOCAL_LEVEL to one of the ESP_LOG_* values, before including esp_log.h in this file.

Parameters

  • tag: Tag of the log entries to enable. Must be a non-NULL zero terminated string. Value “*” resets log level for all tags to the given value.

  • level: Selects log level to enable. Only logs at this and lower verbosity levels will be shown.

vprintf_like_t esp_log_set_vprintf(vprintf_like_t func)

Set function used to output log entries.

By default, log output goes to UART0. This function can be used to redirect log output to some other destination, such as file or network. Returns the original log handler, which may be necessary to return output to the previous destination.

Return

func old Function used for output.

Parameters

  • func: new Function used for output. Must have same signature as vprintf.

uint32_t esp_log_timestamp(void)

Function which returns timestamp to be used in log output.

This function is used in expansion of ESP_LOGx macros. In the 2nd stage bootloader, and at early application startup stage this function uses CPU cycle counter as time source. Later when FreeRTOS scheduler start running, it switches to FreeRTOS tick count.

For now, we ignore millisecond counter overflow.

Return

timestamp, in milliseconds

uint32_t esp_log_early_timestamp(void)

Function which returns timestamp to be used in log output.

This function uses HW cycle counter and does not depend on OS, so it can be safely used after application crash.

Return

timestamp, in milliseconds

void esp_log_write(esp_log_level_t level, const char *tag, const char *format, ...)

Write message into the log.

This function is not intended to be used directly. Instead, use one of ESP_LOGE, ESP_LOGW, ESP_LOGI, ESP_LOGD, ESP_LOGV macros.

This function or these macros should not be used from an interrupt.

Macros

ESP_LOG_BUFFER_HEX_LEVEL(tag, buffer, buff_len, level)

Log a buffer of hex bytes at specified level, separated into 16 bytes each line.

Parameters

  • tag: description tag

  • buffer: Pointer to the buffer array

  • buff_len: length of buffer in bytes

  • level: level of the log

ESP_LOG_BUFFER_CHAR_LEVEL(tag, buffer, buff_len, level)

Log a buffer of characters at specified level, separated into 16 bytes each line. Buffer should contain only printable characters.

Parameters

  • tag: description tag

  • buffer: Pointer to the buffer array

  • buff_len: length of buffer in bytes

  • level: level of the log

ESP_LOG_BUFFER_HEXDUMP(tag, buffer, buff_len, level)

Dump a buffer to the log at specified level.

The dump log shows just like the one below: 

 W (195) log_example: 0x3ffb4280   45 53 50 33 32 20 69 73  20 67 72 65 61 74 2c 20  |ESP32 is great, |
 W (195) log_example: 0x3ffb4290   77 6f 72 6b 69 6e 67 20  61 6c 6f 6e 67 20 77 69  |working along wi|
 W (205) log_example: 0x3ffb42a0   74 68 20 74 68 65 20 49  44 46 2e 00              |th the IDF..|

It is highly recommend to use terminals with over 102 text width.

Parameters

  • tag: description tag

  • buffer: Pointer to the buffer array

  • buff_len: length of buffer in bytes

  • level: level of the log

ESP_LOG_BUFFER_HEX(tag, buffer, buff_len)

Log a buffer of hex bytes at Info level.

See

esp_log_buffer_hex_level

Parameters

  • tag: description tag

  • buffer: Pointer to the buffer array

  • buff_len: length of buffer in bytes

ESP_LOG_BUFFER_CHAR(tag, buffer, buff_len)

Log a buffer of characters at Info level. Buffer should contain only printable characters.

See

esp_log_buffer_char_level

Parameters

  • tag: description tag

  • buffer: Pointer to the buffer array

  • buff_len: length of buffer in bytes

ESP_EARLY_LOGE(tag, format, ...)

macro to output logs in startup code, before heap allocator and syscalls have been initialized. log at ESP_LOG_ERROR level.

See

printf,ESP_LOGE

ESP_EARLY_LOGW(tag, format, ...)

macro to output logs in startup code at ESP_LOG_WARN level.

See

ESP_EARLY_LOGE,ESP_LOGE, printf

ESP_EARLY_LOGI(tag, format, ...)

macro to output logs in startup code at ESP_LOG_INFO level.

See

ESP_EARLY_LOGE,ESP_LOGE, printf

ESP_EARLY_LOGD(tag, format, ...)

macro to output logs in startup code at ESP_LOG_DEBUG level.

See

ESP_EARLY_LOGE,ESP_LOGE, printf

ESP_EARLY_LOGV(tag, format, ...)

macro to output logs in startup code at ESP_LOG_VERBOSE level.

See

ESP_EARLY_LOGE,ESP_LOGE, printf

ESP_LOG_EARLY_IMPL(tag, format, log_level, log_tag_letter, ...)
ESP_LOGE(tag, format, ...)
ESP_LOGW(tag, format, ...)
ESP_LOGI(tag, format, ...)
ESP_LOGD(tag, format, ...)
ESP_LOGV(tag, format, ...)
ESP_LOG_LEVEL(level, tag, format, ...)

runtime macro to output logs at a specified level.

See

printf

Parameters

  • tag: tag of the log, which can be used to change the log level by esp_log_level_set at runtime.

  • level: level of the output log.

  • format: format of the output log. see printf

  • ...: variables to be replaced into the log. see printf

ESP_LOG_LEVEL_LOCAL(level, tag, format, ...)

runtime macro to output logs at a specified level. Also check the level with LOG_LOCAL_LEVEL.

See

printf, ESP_LOG_LEVEL

Type Definitions

typedef int (*vprintf_like_t)(const char *, va_list)

Enumerations

enum esp_log_level_t

Log level.

Values:

ESP_LOG_NONE

No log output

ESP_LOG_ERROR

Critical errors, software module can not recover on its own

ESP_LOG_WARN

Error conditions from which recovery measures have been taken

ESP_LOG_INFO

Information messages which describe normal flow of events

ESP_LOG_DEBUG

Extra information which is not necessary for normal use (values, pointers, sizes, etc).

ESP_LOG_VERBOSE

Bigger chunks of debugging information, or frequent messages which can potentially flood the output.