// $Id$
//
-// Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
\see
\ref logging \n
\ref config \n
-
+ \ref targets \n
+ \ref loglevels
+
+ \section logging_concepts Concepts
+
+ Log messages are arbitrarily created throughout the code using simple log statements (which are
+ macros). Besides the log message itself, every log message is labeled with additional
+ information: The \e stream, the \e area and a log \e level. If the message is not compile-time
+ disabled, the message is then directed to one or several log \e targets.
+
+ A \e stream combines log messages with a single purpose: Debug messages, access logging and so
+ on. Any number of streams may be defined. There is one predefined default stream called \c
+ senf::log::Debug. (see: \ref SENF_LOG_DEF_STREAM)
+
+ The \e area gives information about the source location of the message. Areas may be defined and
+ assigned arbitrarily but should be used to label messages from a single class or subsystem. It
+ is possible to reuse a class as it's own area tag, which is often desireable. There is a
+ default area \c senf::log::DefaultArea which is used, when no other area is assigned. (see: \ref
+ SENF_LOG_DEF_AREA, \ref SENF_LOG_CLASS_AREA)
+
+ The log \e level gives information on the importance of the message. The list of log-levels is
+ fixed. (see: \ref loglevels)
+
+ Depending on their the \e stream, \e area and \e level information, log messages can be enabled
+ or disabled at \e compile time. Messages disabled at compile time should not generate any
+ code. (see: \ref SENF_LOG_CONF)
+
+ To be of any use, the log messages have to be written somewhere. This is the responsibility of
+ any number of \e targets. A \e target receives messages and using it's routing information
+ decides, wether the message is output or not. A message may be routed to multiple targets
+ simultaneously or may not be output by any target at all. (see: \ref targets)
+
\section logging_tutorial Tutorial introduction
Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
// This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
SENF_LOG_CLASS_AREA();
- // Set default log parameters for this scope. The values here are not really
- // necessary since these are the global default values
+ // Set default log parameters for this scope.
SENF_LOG_DEFAULT_STREAM(foo::UserLog);
SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
}
+
+ int main(int, char **)
+ {
+ // Set up the routing targets
+ senf::log::ConsoleTarget & console (senf::log::ConsoleTarget::instance());
+ senf::log::FileTarget logfile ("my.log");
+
+ // Debug messages go to the console
+ console.route<senf::log::Debug>();
+ // Important user message are written to the log file
+ logfile.route<foo::UserLog, senf::log::IMPORTANT>();
+ }
\endcode
\implementation I would have much preferred a more C++ like implementation. However given the
design goals
\li Flexible configuration at compile and runtime
\li Concise usage and simple interface
- \li Zero overhead for compile-time disabled log messages I did not find any non-mcaro
- implementation which was not either completely convoluted, unusable or slow. So I turned to
- a macro based implementation which can provide all the design goals stated above.
+ \li Zero overhead for compile-time disabled log messages
+
+ I did not find any non-mcaro implementation which was not either completely convoluted,
+ unusable or slow. So I turned to a macro based implementation which can provide all the
+ design goals stated above.
*/
\f
projects / senf.git / blobdiff