Logging library¶
Overview¶
The logging library provides two ways for setting log verbosity:
At compile time: in menuconfig, set the verbosity level using the option
CONFIG_LOG_DEFAULT_LEVEL
. All logging statements for verbosity levels higher thanCONFIG_LOG_DEFAULT_LEVEL
will be removed by the preprocessor.At runtime: all logs for verbosity levels lower than
CONFIG_LOG_DEFAULT_LEVEL
are enabled by default. The functionesp_log_level_set()
can be used to set a logging level on a per module basis. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
There are the following verbosity levels:
Error (lowest)
Warning
Info
Debug
Verbose (highest)
注解
The function esp_log_level_set()
cannot set logging levels higher than specified by CONFIG_LOG_DEFAULT_LEVEL
. To increase log level for a specific file at compile time, use the macro LOG_LOCAL_LEVEL (see the details below).
How to use this library¶
In each C file that uses logging functionality, define the TAG variable as shown below:
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
- warningESP_LOGI
- infoESP_LOGD
- debugESP_LOGV
- verbose (highest)
Additionally, there are ESP_EARLY_LOGx
versions for each of these macros, e.g., ESP_EARLY_LOGE
. These versions have to be used explicitly in the early startup code only, before heap allocator and syscalls have been initialized. Normal ESP_LOGx
macros can also be used while compiling the bootloader, but they will fall back to the same implementation as ESP_EARLY_LOGx
macros.
To override default verbosity level at file or component scope, define the 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 the component makefile:
CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
To configure logging output per module at runtime, add calls to the function esp_log_level_set()
as follows:
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
Application Example¶
The logging library is commonly used by most esp-idf components and examples. For demonstration of log functionality, check ESP-IDF’s examples directory. The most revelant examples that deal with logging are the following:
API Reference¶
Header File¶
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
-
char *
esp_log_system_timestamp
(void)¶ Function which returns system timestamp to be used in log output.
This function is used in expansion of ESP_LOGx macros to print the system time as “HH:MM:SS.sss”. The system time is initialized to 0 on startup, this can be set to the correct time with an SNTP sync, or manually with standard POSIX time functions.
Currently this will not get used in logging from binary blobs (i.e WiFi & Bluetooth libraries), these will still print the RTOS tick time.
- Return
timestamp, in “HH:MM:SS.sss”
-
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.
-
void
esp_log_writev
(esp_log_level_t level, const char *tag, const char *format, va_list args)¶ Write message into the log, va_list variant.
This function is provided to ease integration toward other logging framework, so that esp_log can be used as a log sink.
- See
esp_log_write()
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 tagbuffer
: Pointer to the buffer arraybuff_len
: length of buffer in byteslevel
: 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 tagbuffer
: Pointer to the buffer arraybuff_len
: length of buffer in byteslevel
: 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 tagbuffer
: Pointer to the buffer arraybuff_len
: length of buffer in byteslevel
: 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 tagbuffer
: Pointer to the buffer arraybuff_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 tagbuffer
: Pointer to the buffer arraybuff_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 byesp_log_level_set
at runtime.level
: level of the output log.format
: format of the output log. seeprintf
...
: variables to be replaced into the log. seeprintf
-
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
-
ESP_DRAM_LOGE
(tag, format, ...)¶ Macro to output logs when the cache is disabled. log at
ESP_LOG_ERROR
level.Similar to
ESP_EARLY_LOGE
, the log level cannot be changed byesp_log_level_set
.Usage:
ESP_DRAM_LOGE(DRAM_STR("my_tag"), "format", or
ESP_DRAM_LOGE(TAG, “format”, …)`, where TAG is a char* that points to a str in the DRAM.- Note
Placing log strings in DRAM reduces available DRAM, so only use when absolutely essential.
- See
esp_rom_printf
,ESP_LOGE
-
ESP_DRAM_LOGW
(tag, format, ...)¶ macro to output logs when the cache is disabled at
ESP_LOG_WARN
level.- See
ESP_DRAM_LOGW
,ESP_LOGW
,esp_rom_printf
-
ESP_DRAM_LOGI
(tag, format, ...)¶ macro to output logs when the cache is disabled at
ESP_LOG_INFO
level.- See
ESP_DRAM_LOGI
,ESP_LOGI
,esp_rom_printf
-
ESP_DRAM_LOGD
(tag, format, ...)¶ macro to output logs when the cache is disabled at
ESP_LOG_DEBUG
level.- See
ESP_DRAM_LOGD
,ESP_LOGD
,esp_rom_printf
-
ESP_DRAM_LOGV
(tag, format, ...)¶ macro to output logs when the cache is disabled at
ESP_LOG_VERBOSE
level.- See
ESP_DRAM_LOGV
,ESP_LOGV
,esp_rom_printf
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.
-