4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
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 The log messages are devided along several categories: \e streams, \e areas and log \e levels.
42 A \e stream combines log messages with a single purpose. There is one default stream, called \c
43 senf::log::Debug. New streams are defined with \ref SENF_LOG_DEF_STREAM.
45 An \e area labels a log message with the source location of the message. An area is an arbitrary
46 tag which may be added to the message. There is one default area called \c
47 senf::log::DefaultArea. New areas are defined either with \ref SENF_LOG_DEF_AREA or \ref
48 SENF_LOG_CLASS_AREA, the latter being the more typical. The area will normally indicate the
49 class or subsystem from which the message was generated.
51 The log \e level gives information on the importance of the message. The list lof \ref loglevels
54 After log messages have been created, they have to be placed somewhere. This is the
55 responsibility of the \e target. A target is an arbitrary sink for log messages. The target
56 manages message routing and will pass the message on to it's destination, be it the system
57 console, some log file or some other place (e.g. an SQL database). The target is responsible for
58 formating the message.
60 \section logging_tutorial Tutorial introduction
62 Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
63 some other helpers used to simplify specifying parameters.
68 // Define a new log stream with default level, runtime limit and compile time limit
69 // set to senf::log::MESSAGE
70 SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
74 // Define a log area which will automatically be used by all members of this class.
75 // This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
76 SENF_LOG_CLASS_AREA();
78 // Set default log parameters for this scope.
79 SENF_LOG_DEFAULT_STREAM(foo::UserLog);
80 SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
82 // Define an alias for emergency debug messages
83 // The log area is inherited from the default at the place, where this
84 // alias is used *not* where it is defined
85 SENF_LOG_DEF_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
94 void foo::Froblizer::froblize()
96 SENF_LOG(("This is the UserLog at level NOTICE in the FroblizeArea"));
97 SENF_LOG((senf::log::WARNING) ("Same stream and area but at warning level"));
98 SENF_LOG((LogEmerg) ("This goes to the DebugLog at level CRITICAL in the FroblizerArea"));
101 void foo::Froblizer::test()
103 // Change the default log level for this method. stream and area are taken
104 // from the next scope up
105 SENF_LOG_DEFAULT_LEVEL(senf::log::VERBOSE);
107 SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
111 \implementation I would have much preferred a more C++ like implementation. However given the
113 \li Flexible configuration at compile and runtime
114 \li Concise usage and simple interface
115 \li Zero overhead for compile-time disabled log messages
117 I did not find any non-mcaro implementation which was not either completely convoluted,
118 unusable or slow. So I turned to a macro based implementation which can provide all the
119 design goals stated above.
126 // comment-column: 40
127 // c-file-style: "senf"
128 // indent-tabs-mode: nil
129 // ispell-local-dictionary: "american"
130 // compile-command: "scons -u test"