1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
/*! \page page_logging UHD Logging
During the operation of UHD, logging messages are created which UHD handles in a
logging subsystem. Everything logging-related is defined in
include/uhd/utils/log.hpp. See also \ref loghpp_logging
UHD itself never prints anything to stdout, which means that stdout can be used
for applications using UHD. Actual logging messages are handled by separate
logging backends. By default, UHD has two backends: A *console* backend, which
prints logging messages to stderr (more accurately, to `std::clog`), and
a *file* backend, which writes all logging messages into a log file.
\section logging_levels Log levels
UHD defines the following log levels (see also \ref loghpp_levels):
- Trace: Typical trace messages are along the lines of "this function is
currently being executed" or "this is the current state of my local scope, the
following variables have the following values". Trace message are numerous,
and should usually be safe to ignore, unless some tricky debugging is
happening which requires knowing exactly what UHD is doing when and where and
how.
- Debug: Messages should have this level when it's likely the message can be
useful for debugging errorneus behaviour. A good reason to use debug level
messages is when user input is in the mix.
- Info: Whenever a message is usually supposed to be seen by the user, but it's
indicating regular behaviour, it's 'info'. Message at this level are rare.
- Warning: Anything that indicates something could be wrong, but operation can
continue for now, is a warning.
- Error: If something goes wrong, it's an error message. This is typically
accompanied by termination of the program.
- Fatal: SOMETHING'S REALLY WRONG
Whenever a log level is set, it means all log levels with higher severity are
also printed. Example: If the log level is set to 'debug', it won't print
messages that are at 'trace' severity, but it will print 'info' and all the
other levels.
There are multiple ways to set the log level:
- Minimum level: This is a compile-time option. At compile-time, it disables
all log messages permanently that are below this log level.
- Global level: The global level can be changed at runtime, and applies to all
backends.
- Per-backend level: For example, The logfile and the console output could have
different logging levels.
Log levels are evaluated in this order. If the minimum level is 'debug', no
'trace' message will ever be printed. If the global level is 'info', no 'debug'
message will ever be printed -- but this can be changed at runtime. Finally,
if a message has passed both the minimum and global levels, it is handled by
the individual backends if their log levels are appropriately set.
For more info on how to set the individual log levels, see
include/uhd/utils/log.hpp.
\section logging_macros Logging Macros
When log messages are generated, the appropriate logging macros should always
be used. There are two types of macros:
~~~~~~~~~~~~~~{.cpp}
UHD_LOG_DEBUG("component", "message");
UHD_LOGGER_DEBUG("component") << "message";
~~~~~~~~~~~~~~
The difference between those is, the former style is completely compiled out
when the minimum log level is set accordingly, whereas the second one is not,
but offers more flexibility through the streaming operators.
Use the former if speed matters.
The macros require three pieces of information:
- The log level. This is done by choosing the appropriate macro, e.g.,
`UHD_LOGGER_DEBUG` vs. `UHD_LOGGER_INFO`.
- The component where the log message is originating from. This allows to filter
log messages more easily.
- The log message itself.
\section logging_backends Logging Backends
Anything that acts upon a log message is called a backend. UHD defines two by
default: A logfile, and a console backend. More backends can be added by
calling uhd::log::add_logger().
*/
// vim:ft=doxygen:
|
