Utils/Logger/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   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.
  12 //
  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.
  17 //
  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.
  22
  23 /** \mainpage The SENF Logging library
  24
  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.
  31
  32     \see
  33         \ref logging \n
  34         \ref config \n
  35         \ref targets \n
  36         \ref loglevels
  37
  38     \section logging_concepts Concepts
  39
  40     The log messages are devided along several categories: \e streams, \e areas and log \e levels.
  41
  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.
  44
  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.
  50
  51     The log \e level gives information on the importance of the message. The list lof \ref loglevels
  52     is fixed.
  53
  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.
  59
  60     \section logging_tutorial Tutorial introduction
  61
  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.
  64
  65     \code
  66     namespace foo {
  67
  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 );
  71
  72         class Froblizer
  73         {
  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();
  77
  78             // Set default log parameters for this scope.
  79             SENF_LOG_DEFAULT_STREAM(foo::UserLog);
  80             SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
  81
  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));
  86
  87             void test();
  88
  89         public:
  90             void froblize();
  91         };
  92     }
  93
  94     void foo::Froblizer::froblize()
  95     {
  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"));
  99     }
 100
 101     void foo::Froblizer::test()
 102     {
 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);
 106
 107         SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
 108     }
 109     \endcode
 110
 111     \implementation I would have much preferred a more C++ like implementation. However given the
 112         design goals
 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
 116
 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.
 120  */
 121
 122 \f
 123 // Local Variables:
 124 // mode: c++
 125 // fill-column: 100
 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"
 131 // mode: flyspell
 132 // mode: auto-fill
 133 // End: