4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief Config public header */
32 //#include "Config.mpp"
34 ///////////////////////////////hh.p////////////////////////////////////////
36 /** \defgroup config Configuration
38 The logger infrastructure provides for very fine-grained configuration of log messages. There
39 are two parts to this configuration: compile-time configuration and runtime configuration.
41 <em>Compile-time</em> configuration selects, which log statements will even be compiled. If
42 logging for a certain combination of stream, area and level is disabled at compile time, no code
43 will be generated for any such disabled log statement. This type of configuration is done using
46 <em>Runtime</em> configuration on the other hand deals with routing all those messages, which
47 are enabled at compile time to the logging targets. If a message is not routed, it will be
48 discarded. This allows to additionally disable messages at run-time. Message routing is managed
49 via the ::Target interface.
51 \section config_compile Compile time configuration
53 Compile time configuration is set on the compiler command line:
55 g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
56 (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
57 (( (foo)(Transactions),(_),NOTICE ))" ...
59 The value is relatively complex; It's a Boost.Preprocessor style sequence of tuples, of which
60 the first and second elements are again sequences. What this boils down to, is that it allows to
61 configure compile time logging limits based on stream and optional area.
63 The above example disables all debug logging by setting the default log limit for all areas on
64 the \c senf::log::Debug stream to \c DISABLED. It then re-enables debug logging only within the
65 \c foo::SomeClass area, where it is set to \c VERBOSE. Furthermore, the limit on the \c
66 foo::Transactions stream is set to \c NOTICE.
68 There are two standard uses for this configuration: Either to disable most logging in final
69 builds by changing the compile time limit to something like senf::log::IMPORTANT or to enable
70 senf::log::VERBOSE messages for some area:
72 # Disable debug logging below 'IMPORTANT' level
73 g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug), (_), IMPORTANT ))"
75 # Or enable verbose messages for the 'some::Area' area
76 g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Verbose), (some)(Area), VERBOSE ))"
80 \see \ref SENF_LOG_CONF
82 \section config_runtime Runtime configuration
84 The runtime configuration is performed by routing messages to one or more logging targets:
86 senf::log::ConsoleLog & consoleLog (senf::log::ConsoleLog::instance());
87 senf::log::FileLog fileLog ("my.log");
89 consoleLog.route<senf::log::Debug>();
90 consoleLog.route<foo::Transactions, foo::SomeClass>(senf::log::Target::REJECT);
91 consoleLog.route<foo::Transactions, senf::log::IMPORTANT>();
93 fileLog.route<foo::Transactions>();
95 Here we see an already relatively complex setup: All debug messages (that is, those, which are
96 not disabled at compile time) are routed to the console. We also route important transactions to
97 the console \e except transactions from the \c foo::SomeClass area. The \c fileLog simply
98 receives all transaction log messages.
100 The routing statements are processed by the targets in order, the first matching rule will
101 decide a log messages fate for that target.
103 \section config_fallback Fallback routing
105 There are two cases, where this setup may lead to inadvertently lost log messages:
106 \li When using a library which does internally use the Logger but not initializing the logger in
108 \li When log messages are created during initialization of static objects.
109 Since no route is set up in these cases, the messages will be dropped.
111 To counter this problem, the logger is initially in <em>fallback routing</em> state. If any log
112 message arrives in this state, the message will be logged to the console if it is above the
113 default runtime limit of it's stream. The first routing statement on any target will take the
114 logger out of this state and normal routing will take place.
116 \see \ref senf::log::Target
118 \section config_timesource Log message timing
120 One auxiliary aspect of logging is message timing. Each message is stamped with a time-stamp
121 giving the exact time the message was created. How the current date/time value is created may be
122 changed by setting a \e TimeSource. A TimeSource is an instance derived from
123 senf::log::TimeSource which will return the current universal time (UTC) when called.
125 By default, the logging library will call gettimeofday() for each log message. To change the
126 time source, just pass the new class or instance to senf::log::timeSource:
128 // Use senf::Scheduler::instance().eventTime() to time log messages
129 senf::log::timeSource<senf::SchedulerLogTimeSource>();
141 /** \brief Compile time configuration
143 This define symbol sets the compile time logger configuration. This symbol should normally
144 be set on the compiler command line.
146 The formal syntax of this option is:
150 <tr><td>conf</td> <td>::= \e element \e element* \n</td></tr>
151 <tr><td>element</td> <td>::= <tt>((</tt> \e stream <tt>,</tt> \e optional_area <tt>,</tt> \e level <tt>))</tt> \n</td></tr>
152 <tr><td>stream</td> <td>::= \e scope_seq \n</td></tr>
153 <tr><td>optional_area</td><td>::= <tt>(_)</tt> | \e scope_seq \n</td></tr>
154 <tr><td>level</td> <td>::= \c VERBOSE | \c NOTICE | \c MESSAGE | \c IMPORTANT | \c CRITICAL | \c DISABLED \n</td></tr>
155 <tr><td>scope_seq</td> <td>::= \e scope \e scope* \n</td></tr>
156 <tr><td>scope</td> <td>::= <tt>(</tt> \e name <tt>)</tt> \n</td></tr>
157 <tr><td>name</td> <td>::= arbitrary C++ identifier</td></tr>
160 \ref SENF_LOG_CONF is a Boost.Preprocessor style sequence of 3-tuples. Each tuple applies to
161 a specific stream which is defined by the first tuple element \e stream.
163 The next tuple element, \e optional_area optionally restricts the entry to match only the
166 The last tuple element \e level defines the compile time log level. Messages with a level
167 below this are discarded at compile time.
169 Both \e stream and \e optional_area are given as a \e scope_seq. A scope sequence is a fully
170 qualified C++ identifier placed into a sequence: <tt>foo::bar::baz</tt> is represented by
171 <tt>(foo)(bar)(baz)</tt>.
173 # define SENF_LOG_CONF
177 /** \brief Check, if logging is enabled for stream/area/level tuple
179 This is a template meta-function which will check, whether logging to the given combination
180 of parameters \a Stream, \a Area and \a Level is compile-time enabled. The logging might
181 still be disabled at runtime.
183 if (senf::log::Enabled<senf::log::Debug,
184 senf::log::DefaultArea,
185 senf::log::VERBOSE>::value) {
190 Since the \e value member is a compile time constant, the compiler will completely optimize
191 away this block of code when logging is disabled.
193 template <class Stream, class Area, class Level>
196 static const bool value = (
197 (Level::value == NONE::value ? Stream::defaultLevel::value : Level::value)
198 >= detail::Config<Stream,Area>::compileLimit::value );
205 ///////////////////////////////hh.e////////////////////////////////////////
206 //#include "Config.cci"
207 //#include "Config.ct"
208 //#include "Config.cti"
215 // comment-column: 40
216 // c-file-style: "senf"
217 // indent-tabs-mode: nil
218 // ispell-local-dictionary: "american"
219 // compile-command: "scons -u test"