From: g0dil Date: Tue, 30 Oct 2007 14:31:37 +0000 (+0000) Subject: Utils/Logger: Documentation X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=8cc565c01abff7d88fb3bf50f87222f9cad1e9f7;p=senf.git Utils/Logger: Documentation git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@482 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Utils/Logger/AreaRegistry.hh b/Utils/Logger/AreaRegistry.hh index 8decd55..bd14e77 100644 --- a/Utils/Logger/AreaRegistry.hh +++ b/Utils/Logger/AreaRegistry.hh @@ -43,11 +43,13 @@ namespace log { /** \brief Area registry - The area registry keeps track of all areas defined. Area classes are defined as singletons - and will automatically register with this registry. + The area registry keeps track of all areas defined. - The area registry exposes a forward sequence interface which is a sequence of the names of - all registered areas. + The area registry exposes a forward sequence interface which allows to query the list of all + registered areas. + + \implementation Area classes are defined as singletons and will automatically register with + this registry. */ class AreaRegistry : public senf::singleton @@ -62,6 +64,7 @@ namespace log { public: typedef boost::transform_iterator iterator; + ///< Iterator type # ifdef DOXYGEN // Hmm ... doxygen does not understand using declarations ... @@ -71,8 +74,8 @@ namespace log { using senf::singleton::instance; - iterator begin(); - iterator end(); + iterator begin(); ///< Beginning of area name sequence + iterator end(); ///< End of area name sequence private: AreaRegistry(); diff --git a/Utils/Logger/Config.hh b/Utils/Logger/Config.hh index 9725f04..7ec3c7f 100644 --- a/Utils/Logger/Config.hh +++ b/Utils/Logger/Config.hh @@ -47,6 +47,47 @@ 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. + + \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. + + \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::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. + + \see + \ref SENF_LOG_CONF: compile time configuration \n + \ref senf::log::Target: runtime configuration */ namespace senf { @@ -60,13 +101,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: diff --git a/Utils/Logger/IOStreamTarget.hh b/Utils/Logger/IOStreamTarget.hh index 745ee79..94f9999 100644 --- a/Utils/Logger/IOStreamTarget.hh +++ b/Utils/Logger/IOStreamTarget.hh @@ -56,9 +56,6 @@ namespace log { \note This class will permanently and globally change the date formating of the given stream. - - \fixme Implement more robust formatting: Find line-breaks in the message and repeat the - prefix (with continuation markers) */ class IOStreamTarget : public Target diff --git a/Utils/Logger/Log.hh b/Utils/Logger/Log.hh index 5c388fc..028d14e 100644 --- a/Utils/Logger/Log.hh +++ b/Utils/Logger/Log.hh @@ -49,15 +49,16 @@ SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") ); \endcode - For each log message, the following information is needed: + The argument is comprised of a sequence of parameters and the log message itself. The parameters + are \li The log stream, \li the log area, \li the log level, - \li and the log message itself - These parameters may be specified in arbitrary order and even multiple times in the - parameter sequence. If some argument type occurs multiple times, the last occurrence wins. If - any one of the parameters is not specified, it's current default value will be used. + These parameters are optional and may be specified in arbitrary order (with the log + message always being the last sequence element) and even multiple times in the parameter + sequence. If some argument type occurs multiple times, the last occurrence wins. If any one of + the parameters is not specified, it's current default value will be used. This current default value is set using \ref SENF_LOG_DEFAULT_STREAM, \ref SENF_LOG_DEFAULT_AREA and \ref SENF_LOG_DEFAULT_LEVEL respectively. These macros set the default stream, area and/or diff --git a/Utils/Logger/Mainpage.dox b/Utils/Logger/Mainpage.dox index 5905c89..30b80fa 100644 --- a/Utils/Logger/Mainpage.dox +++ b/Utils/Logger/Mainpage.dox @@ -32,7 +32,31 @@ \see \ref logging \n \ref config \n + \ref targets \n + \ref loglevels + \section logging_concepts Concepts + + The log messages are devided along several categories: \e streams, \e areas and log \e levels. + + A \e stream combines log messages with a single purpose. There is one default stream, called \c + senf::log::Debug. New streams are defined with \ref SENF_LOG_DEF_STREAM. + + An \e area labels a log message with the source location of the message. An area is an arbitrary + tag which may be added to the message. There is one default area called \c + senf::log::DefaultArea. New areas are defined either with \ref SENF_LOG_DEF_AREA or \ref + SENF_LOG_CLASS_AREA, the latter being the more typical. The area will normally indicate the + class or subsystem from which the message was generated. + + The log \e level gives information on the importance of the message. The list lof \ref loglevels + is fixed. + + After log messages have been created, they have to be placed somewhere. This is the + responsibility of the \e target. A target is an arbitrary sink for log messages. The target + manages message routing and will pass the message on to it's destination, be it the system + console, some log file or some other place (e.g. an SQL database). The target is responsible for + formating the message. + \section logging_tutorial Tutorial introduction Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are