X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Utils%2FLogger%2FConfig.hh;h=9f0f73541b202cc46897aad2b559ff02446f098c;hb=412024ed31a4ab4eaea7a4165a434f8efebee325;hp=8e0eda33fa4e449faf69b387e27c7e7eff16d9eb;hpb=9060358b468cab462be61aa34e93f7dfd60894f2;p=senf.git diff --git a/Utils/Logger/Config.hh b/Utils/Logger/Config.hh index 8e0eda3..9f0f735 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 @@ -23,8 +23,8 @@ /** \file \brief Config public header */ -#ifndef HH_Config_ -#define HH_Config_ 1 +#ifndef HH_SENF_Utils_Logger_Config_ +#define HH_SENF_Utils_Logger_Config_ 1 // Custom includes #include "Levels.hh" @@ -46,7 +46,7 @@ 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. Message routing is managed - via the \ref Target interface. + via the ::Target interface. \section config_compile Compile time configuration @@ -54,16 +54,42 @@ 
     g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
                              (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
-                             (( (foo)(Transactions),(_),NOTICE ))" ...
+                             (( (_),(_),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. + 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. + the \c senf::log::Debug stream to \c DISABLED. It enables debug logging only within the \c + foo::SomeClass area, where it is set to \c VERBOSE. Lastly, the global compile time limit 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 ))"
+
+ + All the entries specified via \c SENF_LOG_CONF are applied in a fixed order: + + \li First the entries which have both a stream and an area specified are checked + \li next all entries with area but no stream given are checked + \li followed by all entries with a given stream but no area + \li and lastly if no match was found until now, a generic entry without stream and area is + checked + \li if no matching entry is found, the default compile time limit of the stream is used + + So an area specification has precedence over a stream specification. + + \warning Enabling a message at compile time does \e not ensure, the message is shown. You + additionally need to \e route the message (see next chapter). This is especially true for \c + VERBOSE messages, which are default disabled at runtime. \see \ref SENF_LOG_CONF @@ -71,8 +97,8 @@ 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"); + senf::log::ConsoleTarget & consoleLog (senf::log::ConsoleTarget::instance()); + senf::log::FileTarget fileLog ("my.log"); consoleLog.route(); consoleLog.route(senf::log::Target::REJECT); @@ -87,6 +113,12 @@ The routing statements are processed by the targets in order, the first matching rule will decide a log messages fate for that target. + + \warning You can \e only route those messages at runtime which have been compile-time + enabled. By default, \c VERBOSE messages are \e disabled at compile time. They must be + enabled \e explicitly by setting \c SENF_LOG_CONF so they can be routed. + + \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 @@ -95,9 +127,9 @@ 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 unconditionally logged to the console. The - first routing statement on any target will take the logger out of this state and normal routing - will take place. + 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 @@ -111,8 +143,8 @@ 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(); + // Use senf::scheduler::eventTime() to time log messages + senf::log::timeSource(); \endcode */ @@ -133,28 +165,30 @@ namespace log { \par "" - - - - - - - - + + + + + + + +
conf ::= \e element \e element* \n
element ::= (( \e stream , \e optional_area , \e level )) \n
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 ::= ( \e name ) \n
name ::= arbitrary C++ identifier
conf ::= \e element \e element* \n
element ::= (( \e optional_stream , \e optional_area , \e level )) \n
optional_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* \n
scope ::= ( \e name ) \n
name ::= arbitrary C++ identifier
- \ref SENF_LOG_CONF is a Boost.Preprocessor style sequence of 3-tuples. Each tuple applies to - a specific stream which is defined by the first tuple element \e stream. + \ref SENF_LOG_CONF is a Boost.Preprocessor style sequence of 3-tuples. + + The first tuple element \e optional_stream specifies the stream to match. If this is + (_), the entry will match any stream. The next tuple element, \e optional_area optionally restricts the entry to match only the - given area. + given area. If set to (_), the area is left unrestricted. The last tuple element \e level defines the compile time log level. Messages with a level below this are discarded at compile time. - Both \e stream and \e optional_area are given as a \e scope_seq. A scope sequence is a fully - qualified C++ identifier placed into a sequence: foo::bar::baz is represented by - (foo)(bar)(baz). + Both \e optional_stream and \e optional_area are given as a \e scope_seq. A scope sequence + is a fully qualified C++ identifier placed into a sequence: foo::bar::baz is + represented by (foo)(bar)(baz). */ # define SENF_LOG_CONF