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.
23 /** \mainpage The SENF Logging library
25 The Loggger infrastructure implements a highly flexible compile- and run-time configurable
26 logging infrastructure supporting multiple streams, user definable log areas and fine grained
27 log levels. Logging can be configured at compile and runtime on any combination of above
28 parameters. The library supports a host of log targets and messages can be routed into multiple
29 targets at the same time. To allow concise usage of the library, a utility to define logging
30 defaults for any scope is provided.
38 \section logging_concepts Concepts
40 Log messages are arbitrarily created throughout the code using simple log statements (which are
41 macros). Besides the log message itself, every log message is labeled with additional
42 information: The \e stream, the \e area and a log \e level. If the message is not compile-time
43 disabled, the message is then directed to one or several log \e targets.
45 A \e stream combines log messages with a single purpose: Debug messages, access logging and so
46 on. Any number of streams may be defined. There is one predefined default stream called \c
47 senf::log::Debug. (see: \ref SENF_LOG_DEFINE_STREAM)
49 The \e area gives information about the source location of the message. Areas may be defined and
50 assigned arbitrarily but should be used to label messages from a single class or subsystem. It
51 is possible to reuse a class as it's own area tag, which is often desireable. There is a
52 default area \c senf::log::DefaultArea which is used, when no other area is assigned. (see: \ref
53 SENF_LOG_DEFINE_AREA, \ref SENF_LOG_CLASS_AREA)
55 The log \e level gives information on the importance of the message. The list of log-levels is
56 fixed. (see: \ref loglevels)
58 Depending on their the \e stream, \e area and \e level information, log messages can be enabled
59 or disabled at \e compile time. Messages disabled at compile time should not generate any
60 code. (see: \ref SENF_LOG_CONF)
62 \attention The default log stream senf::log::Debug has senf::log::VERBOSE messages
63 <em>disabled</em> at compile time. senf::log::VERBOSE message will therefore only appear,
64 if you explictly enable the messages for the area in question using (here for the area
65 <code>some::Area</code>)
67 g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug), (some)(Area), VERBOSE ))"
69 in addition to routing the messages at runtime. For more, see \ref config.
71 To be of any use, the log messages have to be written somewhere. This is the responsibility of
72 any number of \e targets. A \e target receives messages and using it's routing information
73 decides, wether the message is output or not. A message may be routed to multiple targets
74 simultaneously or may not be output by any target at all. (see: \ref targets)
76 \section logging_tutorial Tutorial introduction
78 Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
79 some other helpers used to simplify specifying parameters.
84 // Define a new log stream with default level, runtime limit and compile time limit
85 // set to senf::log::MESSAGE
86 SENF_LOG_DEFINE_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
90 // Define a log area which will automatically be used by all members of this class.
91 // This is a combination of SENF_LOG_DEFINE_AREA and SENF_LOG_DEFAULT_AREA.
92 SENF_LOG_CLASS_AREA();
94 // Set default log parameters for this scope.
95 SENF_LOG_DEFAULT_STREAM(foo::UserLog);
96 SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
98 // Define an alias for emergency debug messages
99 // The log area is inherited from the default at the place, where this
100 // alias is used *not* where it is defined
101 SENF_LOG_DEFINE_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
110 void foo::Froblizer::froblize()
112 SENF_LOG(("This is the UserLog at level NOTICE in the FroblizeArea"));
113 SENF_LOG((senf::log::IMPORTANT) ("Same stream and area but at important level"));
114 SENF_LOG((LogEmerg) ("This goes to the DebugLog at level CRITICAL in the FroblizerArea"));
117 void foo::Froblizer::test()
119 // Change the default log level for this method. stream and area are taken
120 // from the next scope up
121 SENF_LOG_DEFAULT_LEVEL(senf::log::VERBOSE);
123 SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
126 int main(int, char **)
128 // Set up the routing targets
129 senf::log::ConsoleTarget & console (senf::log::ConsoleTarget::instance());
130 senf::log::FileTarget logfile ("my.log");
132 // Debug messages go to the console
133 console.route<senf::log::Debug>();
134 // Important user message are written to the log file
135 logfile.route<foo::UserLog, senf::log::IMPORTANT>();
139 \implementation I would have much preferred a more C++ like implementation. However given the
141 \li Flexible configuration at compile and runtime
142 \li Concise usage and simple interface
143 \li Zero overhead for compile-time disabled log messages
145 I did not find any non-mcaro implementation which was not either completely convoluted,
146 unusable or slow. So I turned to a macro based implementation which can provide all the
147 design goals stated above.
154 // comment-column: 40
155 // c-file-style: "senf"
156 // indent-tabs-mode: nil
157 // ispell-local-dictionary: "american"
158 // compile-command: "scons -u test"