X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Utils%2FLogger%2FConfig.hh;h=ec23c7f688c3070ac424c62ad840a74682f93551;hb=10985d71f77b627bc4da543d7114feb7c4529329;hp=a9bf7c7a49ce12ec6c2b12d168a2b2f19e640835;hpb=61419d9a2e1060f7ede22fa19fd9d0b401bbc87a;p=senf.git diff --git a/Utils/Logger/Config.hh b/Utils/Logger/Config.hh index a9bf7c7..ec23c7f 100644 --- a/Utils/Logger/Config.hh +++ b/Utils/Logger/Config.hh @@ -1,8 +1,8 @@ // $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 // // This program is free software; you can redistribute it and/or modify @@ -45,7 +45,89 @@ Runtime configuration on the other hand deals with routing all those messages, which are enabled at compile time to the logging targets. If a message is not routed, it will be - discarded. This allows to additionally disable messages at run-time. + discarded. This allows to additionally disable messages at run-time. Message routing is managed + via the ::Target interface. + + \section config_compile Compile time configuration + + Compile time configuration is set on the compiler command line: + 
+    g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
+                             (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
+                             (( (foo)(Transactions),(_),NOTICE ))" ...
+
+ The value is relatively complex; It's a Boost.Preprocessor style sequence of tuples, of which + the first and second elements are again sequences. What this boils down to, is that it allows to + configure compile time logging limits based on stream and optional area. + + The above example disables all debug logging by setting the default log limit for all areas on + the \c senf::log::Debug stream to \c DISABLED. It then re-enables debug logging only within the + \c foo::SomeClass area, where it is set to \c VERBOSE. Furthermore, the limit on the \c + foo::Transactions stream is set to \c NOTICE. + + There are two standard uses for this configuration: Either to disable most logging in final + builds by changing the compile time limit to something like senf::log::IMPORTANT or to enable + senf::log::VERBOSE messages for some area: + 
+    # Disable debug logging below 'IMPORTANT' level
+    g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug), (_), IMPORTANT ))"
+
+    # Or enable verbose messages for the 'some::Area' area
+    g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Verbose), (some)(Area), VERBOSE ))"
+
+ + + \see \ref SENF_LOG_CONF + + \section config_runtime Runtime configuration + + The runtime configuration is performed by routing messages to one or more logging targets: + \code + senf::log::ConsoleLog & consoleLog (senf::log::ConsoleLog::instance()); + senf::log::FileLog fileLog ("my.log"); + + consoleLog.route(); + consoleLog.route(senf::log::Target::REJECT); + consoleLog.route(); + + fileLog.route(); + \endcode + Here we see an already relatively complex setup: All debug messages (that is, those, which are + not disabled at compile time) are routed to the console. We also route important transactions to + the console \e except transactions from the \c foo::SomeClass area. The \c fileLog simply + receives all transaction log messages. + + The routing statements are processed by the targets in order, the first matching rule will + decide a log messages fate for that target. + + \section config_fallback Fallback routing + + There are two cases, where this setup may lead to inadvertently lost log messages: + \li When using a library which does internally use the Logger but not initializing the logger in + your application. + \li When log messages are created during initialization of static objects. + Since no route is set up in these cases, the messages will be dropped. + + To counter this problem, the logger is initially in fallback routing state. If any log + message arrives in this state, the message will be logged to the console if it is above the + default runtime limit of it's stream. The first routing statement on any target will take the + logger out of this state and normal routing will take place. + + \see \ref senf::log::Target + + \section config_timesource Log message timing + + One auxiliary aspect of logging is message timing. Each message is stamped with a time-stamp + giving the exact time the message was created. How the current date/time value is created may be + changed by setting a \e TimeSource. A TimeSource is an instance derived from + senf::log::TimeSource which will return the current universal time (UTC) when called. + + By default, the logging library will call gettimeofday() for each log message. To change the + time source, just pass the new class or instance to senf::log::timeSource: + \code + // Use senf::Scheduler::instance().eventTime() to time log messages + senf::log::timeSource(); + \endcode */ namespace senf { @@ -59,13 +141,7 @@ namespace log { /** \brief Compile time configuration This define symbol sets the compile time logger configuration. This symbol should normally - be set on the compiler command line: - 
-        g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
-                                 (( (senf)(log)(Debug),(foo)(SomeClass),(VERBOSE) ))
-                                 (( (foo)(Transactions),(_),NOTICE ))" ...
-
- (As this option can get quite long, you might want to use the '-imacros' option instead) + be set on the compiler command line. The formal syntax of this option is: @@ -76,7 +152,7 @@ namespace log { stream ::= \e scope_seq \n optional_area::= (_) | \e scope_seq \n level ::= \c VERBOSE | \c NOTICE | \c MESSAGE | \c IMPORTANT | \c CRITICAL | \c DISABLED \n - scope_seq ::= \e scope \e scope \e scope* \n + scope_seq ::= \e scope \e scope* \n scope ::= ( \e name ) \n name ::= arbitrary C++ identifier @@ -118,7 +194,7 @@ namespace log { struct Enabled { static const bool value = ( - (Level::value == senf::log::NONE::value ? Stream::defaultLevel::value : Level::value) + (Level::value == NONE::value ? Stream::defaultLevel::value : Level::value) >= detail::Config::compileLimit::value ); };