MDNS plugin: Hacked away jet another uninit-warning if DEBUG=0
[olsrd.git] / README-logging
1 ==============================================
2            Logging in OLSRd 0.5.7
3 ==============================================
4 by Henning Rogge (hrogge@googlemail.com)
5
6
7 OLSRd versions up to 0.5.6 had a strange mix of syslog, printf and OLSR_PRINT
8 macro to create logging entries. Some events were send to multiple logging
9 targets (syslog and OLSR_PRINTF for example), other were just put into one
10 category.
11
12 In addition to this the OLSR_PRINTF debug level tried to put all
13 logging events into a linear sorted priority list. Most times a logging level
14 was creating to many or not enough logging output, frustrating everyone
15 while debugging a problem.
16
17 Finally there were a group of compiler directives to control the amount of
18 debugging code compiled into the routing agent, which is important for
19 embedded hardware distributions (less binary size). There were three macros
20 called DEBUG, NODEBUG and NO_DEBUG_MESSAGES and it wasn't clear which macro
21 was responsible for a certain job.
22
23 The OLSRd 0.5.7 contains a new logging API that allows much more flexibility
24 for logging events. It cleans up the debug-macros grown during the last years,
25 adds a more flexible filter system for logging events from the command line
26 and allows the user control the target of the logging events. Every logging
27 event can contain the filename/linenumber where the event happened to speedup
28 bug hunting.
29
30 The new logging system has three new concepts, log severity, log source and
31 log target.
32
33   !!! Each logging message has ONE severity and ONE source !!!
34
35 Log severity means the importance of a logging event. There are four severity
36 levels:
37
38 - ERROR, something really bad has happened, the OLSRd routing agent will shut
39   down after this message.
40 - WARN, an error has happened but the agent will continue to run.
41 - INFO contains important information for the user, like state of a database
42   (link, tc, ...)
43 - DEBUG has lot's of detailed information for debugging, much of them are
44   useless without looking at the specific source code.
45
46 Log sources are logical parts of the routing agent like NETWORKING, PLUGINS,
47 and LINKS. You can get a list of all log sources by using the command line
48 option "--help=log".
49
50 Log targets are the different 'backends' for logging events. At the moment
51 the OLSRd supports three different targets, which can be used individually
52 or together:
53
54 - STDERR prints all logging events to the console
55 - FILE stores them into an user defined file
56 - SYSLOG puts them into the syslog
57
58
59
60
61     Logging for users
62 ------------------------- 
63
64 The logging system is controlled by a number of command line/config file options.
65
66 log_debug=<source-list>
67 log_info=<source-list>
68 log_warn=<source-list>
69 log_error=<source-list>
70
71   These four options control which log SOURCES are visible down to a certain
72   severity level. The parameter is a comma separated list of log sources. If you
73   set a source for a lower severity level (--log_info=links  for example) and do
74   NOT set the higher severity level (warn for example) the sources are copied
75   there too.
76
77 log_debug=<debug_level>
78
79   This is a simple way to define a few default logging options. It's additional
80   purpose is to provide limited backward compatiblity to the old debugging
81   level option of 0.5.6.
82   
83     debug level -2: no debug output.
84     debug level -1: only ERROR messages.
85     debug level  0: only ERROR and WARNING messages.
86     debug level  1: all ERRORs, all WARNINGs and INFO messages for
87                   MAIN, PLUGINS, ROUTING, LINKS, NEIGHTABLE, 2NEIGH and TC.
88     debug level  2: all ERRORs, WARNINGs and INFOs.
89     debug level  3: all debug messages
90
91   If no debug severity is set (log_debug/info/warn/error) and no debug level is
92   set (log_debug) the routing agent falls back to it's default "log_debug=0".
93
94 log_syslog
95 log_stderr
96 log_file=<filename>
97
98   These three options activate a certain log TARGET. Each log target can be used
99   once. If not set the routing agent falls back to the default "log_stderr".
100
101
102
103
104     Logging for OLSRd developers
105 ------------------------------------
106
107 To use the new logging API you have to include the file "olsr_logging.h".
108
109 There are eight macros to create a logging event, two for each severity level.
110
111 OLSR_DEBUG(source, format, args...)
112 OLSR_INFO(source, format, args...)
113 OLSR_WARN(source, format, args...)
114 OLSR_ERROR(source, format, args...)
115
116 These four macros work like a printf() command with an additional log SOURCE
117 as the first parameter. The source must be a member of the enum log_source
118 (see src/olsr_cfg_data.h). The source LOG_ALL can NOT be used for the macros,
119 it's just for the configuration parser !
120
121 OLSR_DEBUG_NH(source, format, args...)
122 OLSR_INFO_NH(source, format, args...)
123 OLSR_WARN_NH(source, format, args...)
124 OLSR_ERROR_NH(source, format, args...)
125
126 These macros work like the other ones, but don't produce a header with filename,
127 line number, timestamp, ... (NH = no header)
128 You should use them to create multiline logging events (first one macro of the
129 first group of macros, then multiple of this group)
130
131 example:
132
133 OLSR_INFO(LOG_MAIN, "This is the first line of a macro");
134 OLSR_INFO_NH(LOG_MAIN, "and this is the second time...");
135
136
137
138
139     Logging for firmware developers
140 ---------------------------------------
141
142 There are five compiler defines in Makefile.inc that can be used to control
143 the size of the binary of Olsrd.
144
145 DEBUG = 0/1
146
147 Set DEBUG to 1 to add debugger symbols to olsrd.
148 Set DEBUG to 0 to remove debugger symbols and optimize olsrd for size.
149
150 REMOVE_LOG_DEBUG = 0/1
151 REMOVE_LOG_INFO = 0/1
152 REMOVE_LOG_WARN = 0/1
153 REMOVE_LOG_ERROR = 0/1
154
155 Set one of this four defines to 1 to remove all code for creating logging
156 events of this severity level.
157
158 A good way to create a compact OLSRd for small embedded devices would be:
159
160   DEBUG = 0
161   REMOVE_LOG_DEBUG = 1
162   REMOVE_LOG_INFO = 1