1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2023 Intel Corporation. 3 4Log Library 5=========== 6 7The DPDK Log library provides the logging functionality for other DPDK libraries and drivers. 8By default, logs are sent only to standard error output of the process. 9The syslog EAL option can be used to redirect to the stystem logger on Linux and FreeBSD. 10In addition, the log can be redirected to a different stdio file stream. 11 12Log Levels 13---------- 14 15Log messages from apps and libraries are reported with a given level of severity. 16These levels, specified in ``rte_log.h`` are (from most to least important): 17 18#. Emergency 19#. Alert 20#. Critical 21#. Error 22#. Warning 23#. Notice 24#. Information 25#. Debug 26 27At runtime, only messages of a configured level or above (i.e. of higher importance) 28will be emitted by the application to the log output. 29That level can be configured either by the application calling the relevant APIs from the logging library, 30or by the user passing the ``--log-level`` parameter to the EAL via the application. 31 32Setting Global Log Level 33~~~~~~~~~~~~~~~~~~~~~~~~ 34 35To adjust the global log level for an application, 36just pass a numeric level or a level name to the ``--log-level`` EAL parameter. 37For example:: 38 39 /path/to/app --log-level=error 40 41 /path/to/app --log-level=debug 42 43 /path/to/app --log-level=5 # warning 44 45Within an application, the log level can be similarly set using the ``rte_log_set_global_level`` API. 46 47Setting Log Level for a Component 48~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 49 50In some cases, for example, for debugging purposes, 51it may be desirable to increase or decrease the log level for only a specific component, or set of components. 52To facilitate this, the ``--log-level`` argument also accepts an, optionally wildcarded, component name, 53along with the desired level for that component. 54For example:: 55 56 /path/to/app --log-level=lib.eal:crit 57 58 /path/to/app --log-level=lib.*:warning 59 60Within an application, the same result can be got using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. 61 62 63Using Logging APIs to Generate Log Messages 64------------------------------------------- 65 66To output log messages, ``rte_log()`` API function should be used. 67As well as the log message, ``rte_log()`` takes two additional parameters: 68 69* The log level 70* The log component type 71 72The log level is a numeric value as discussed above. 73The component type is a unique id that identifies the particular DPDK component to the logging system. 74To get this id, each component needs to register itself at startup, 75using the macro ``RTE_LOG_REGISTER_DEFAULT``. 76This macro takes two parameters, with the second being the default log level for the component. 77The first parameter, called "type", the name of the "logtype", or "component type" variable used in the component. 78This variable will be defined by the macro, and should be passed as the second parameter in calls to ``rte_log()``. 79In general, most DPDK components define their own logging macros to simplify the calls to the log APIs. 80They do this by: 81 82* Hiding the component type parameter inside the macro so it never needs to be passed explicitly. 83* Using the log-level definitions given in ``rte_log.h`` to allow short textual names to be used in 84 place of the numeric log levels. 85 86The following code is taken from ``rte_cfgfile.c`` and shows the log registration, 87and subsequent definition of a shortcut logging macro. 88It can be used as a template for any new components using DPDK logging. 89 90.. literalinclude:: ../../../lib/cfgfile/rte_cfgfile.c 91 :language: c 92 :start-after: Setting up dynamic logging 8< 93 :end-before: >8 End of setting up dynamic logging 94 95.. note:: 96 97 Because the log registration macro provides the logtype variable definition, 98 it should be placed near the top of the C file using it. 99 If not, the logtype variable should be defined as an "extern int" near the top of the file. 100 101 Similarly, if logging is to be done by multiple files in a component, 102 only one file should register the logtype via the macro, 103 and the logtype should be defined as an "extern int" in a common header file. 104 Any component-specific logging macro should similarly be defined in that header. 105 106Throughout the cfgfile library, all logging calls are therefore of the form: 107 108.. code:: C 109 110 CFG_LOG(ERR, "missing cfgfile parameters"); 111 112 CFG_LOG(ERR, "invalid comment characters %c", 113 params->comment_character); 114 115Log timestamp 116~~~~~~~~~~~~~ 117 118An optional timestamp can be added before each message by adding the ``--log-timestamp`` option. 119For example:: 120 121 /path/to/app --log-level=lib.*:debug --log-timestamp 122 123Multiple alternative timestamp formats are available: 124 125.. csv-table:: Log time stamp format 126 :header: "Format", "Description", "Example" 127 :widths: 6, 30, 32 128 129 "ctime", "Unix ctime", "``[Wed Mar 20 07:26:12 2024]``" 130 "delta", "Offset since last", "``[< 3.162373>]``" 131 "reltime", "Seconds since last or time if minute changed", "``[ +3.001791]`` or ``[Mar20 07:26:12]``" 132 "iso", "ISO-8601", "``[2024-03-20T07:26:12−07:00]``" 133 134To prefix all console messages with ISO format time the syntax is:: 135 136 /path/to/app --log-timestamp=iso 137 138.. note:: 139 140 Timestamp option has no effect if using syslog 141 because the ``syslog()`` service already does timestamping internally. 142 143 144Color output 145~~~~~~~~~~~~ 146 147The log library will highlight important messages. 148This is controlled by the ``--log-color`` option. 149The optional argument describes when color is enabled: 150 151:never: Do not enable color. This is the default behavior. 152 153:auto: Enable color only when printing to a terminal. 154 This is the same as ``--log-color`` with no argument. 155 156:always: Always print color. 157 158For example to enable color in logs if using terminal:: 159 160 /path/to/app --log-color 161 162.. note:: 163 164 Color output is never used for syslog or systemd journal logging. 165