granicus.if.org Git - esp-idf/blob - components/log/README.rst

   1 Logging library
   2 ===============
   3
   4 Overview
   5 --------
   6
   7 Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using :cpp:func:`esp_log_level_set` function.
   8
   9 The log levels are Error, Warning, Info, Debug, and Verbose (from lowest to highest level of verbosity).
  10
  11 At compile time, filtering is done using :envvar:`CONFIG_LOG_DEFAULT_LEVEL` option, set via menuconfig. All logging statements for levels higher than :envvar:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor.
  12
  13 At run time, all logs below :envvar:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. :cpp:func:`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.
  14
  15 Note that :cpp:func:`esp_log_level_set` can not increase logging level beyound that set by :envvar:`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).
  16
  17 How to use this library
  18 -----------------------
  19
  20 In each C file which uses logging functionality, define TAG variable like this:
  21
  22 .. code-block:: c
  23
  24    static const char* TAG = "MyModule";
  25
  26 then use one of logging macros to produce output, e.g:
  27
  28 .. code-block:: c
  29
  30    ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
  31
  32 Several macros are available for different verbosity levels:
  33
  34 * ``ESP_LOGE`` - error (lowest)
  35 * ``ESP_LOGW`` - warning
  36 * ``ESP_LOGI`` - info
  37 * ``ESP_LOGD`` - debug
  38 * ``ESP_LOGV`` - verbose (highest)
  39
  40 Additionally there is an ``_EARLY`` variant for each of these macros (e.g. :c:macro:`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.
  41
  42 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.:
  43
  44 .. code-block:: c
  45
  46    #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
  47    #include "esp_log.h"
  48
  49
  50 At component scope, define it in component makefile:
  51
  52 .. code-block:: make
  53
  54    CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
  55
  56 To configure logging output per module at runtime, add calls to :cpp:func:`esp_log_level_set` function:
  57
  58 .. code-block:: c
  59
  60    esp_log_level_set("*", ESP_LOG_ERROR);        // set all components to ERROR level
  61    esp_log_level_set("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
  62    esp_log_level_set("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client
  63
  64 Logging to Host via JTAG
  65 ^^^^^^^^^^^^^^^^^^^^^^^^
  66
  67 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 :ref:`app_trace-logging-to-host`.
  68