The UHD logging facility
The logger enables UHD library code to easily log events into a file and display messages above a certain level in the terminal. Log entries are time-stamped and stored with file, line, and function. Each call to the UHD_LOG macros is thread-safe. Each thread will aquire the lock for the logger.
Note: More information on the logging subsystem can be found on page_logging.
To disable console logging completely at compile time specify -DUHD_LOG_CONSOLE_DISABLE
during configuration with CMake.
By default no file logging will occur. Set a log file path:
- at compile time by specifying
-DUHD_LOG_FILE=$file_path
- and/or override at runtime by setting the environment variable
UHD_LOG_FILE
Log levels
See also logging_levels.
All log messages with verbosity greater than or equal to the log level (in other words, as often or less often than the current log level) are recorded to std::clog and/or the log file. Log levels can be specified using string or numeric values of uhd::log::severity_level.
The minimum log level is defined by -DUHD_LOG_MIN_LEVEL
at compile time, and this value can be increased at runtime by specifying the UHD_LOG_LEVEL
environment variable. This minimum logging level applies to any form of runtime logging. Thus for example if this minimum is set to 3 (info
), then during runtime no logging at levels below 3 can be provided.
The following set the minimum logging level to 3 (info
):
- Example pre-processor define:
-DUHD_LOG_MIN_LEVEL=3
- Example pre-processor define:
-DUHD_LOG_MIN_LEVEL=info
- Example environment variable:
export UHD_LOG_LEVEL=3
- Example environment variable:
export UHD_LOG_LEVEL=info
The actual log level for console and file logging can be configured by setting UHD_LOG_CONSOLE_LEVEL
or UHD_LOG_FILE_LEVEL
, respectively. The default values for these variables can be defined using the cmake flags -DUHD_LOG_CONSOLE_LEVEL
and -DUHD_LOG_FILE_LEVEL
, respectively.
These variables can be the name of a verbosity enum or integer value:
- Example pre-processor define:
-DUHD_LOG_CONSOLE_LEVEL=3
- Example pre-processor define:
-DUHD_LOG_CONSOLE_LEVEL=info
- Example environment variable:
export UHD_LOG_CONSOLE_LEVEL=3
- Example environment variable:
export UHD_LOG_CONSOLE_LEVEL=info
The UHD_LOG_FILE_LEVEL
variable can be used in the same way.
Log formatting
The log format for messages going into a log file is CSV. All log messages going into a logfile will contain following fields:
- timestamp
- thread-id
- source-file + line information
- severity level
- component/channel information which logged the information
- the actual log message
The log format of log messages displayed on the terminal is plain text with space separated tags prepended. For example:
[INFO] [X300] This is a informational log message
The log format for log output on the console by using these preprocessor defines in CMake:
-DUHD_LOG_CONSOLE_TIME
adds a timestamp [2017-01-01 00:00:00.000000]
-DUHD_LOG_CONSOLE_THREAD
adds a thread-id [0x001234]
-DUHD_LOG_CONSOLE_SRC
adds a sourcefile and line tag [src_file:line]