senf/Utils/Logger/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 //
  24 // Contributor(s):
  25 //   Stefan Bund <g0dil@berlios.de>
  26
  27
  28 /** \mainpage The SENF Logging library
  29
  30     The Loggger infrastructure implements a highly flexible compile- and run-time configurable
  31     logging infrastructure supporting multiple streams, user definable log areas and fine grained
  32     log levels. Logging can be configured at compile and runtime on any combination of above
  33     parameters. The library supports a host of log targets and messages can be routed into multiple
  34     targets at the same time. To allow concise usage of the library, a utility to define logging
  35     defaults for any scope is provided.
  36
  37     \see
  38         \ref logging \n
  39         \ref config \n
  40         \ref targets \n
  41         \ref loglevels
  42
  43     \section logging_concepts Concepts
  44
  45     Log messages are arbitrarily created throughout the code using simple log statements (which are
  46     macros). Besides the log message itself, every log message is labeled with additional
  47     information: The \e stream, the \e area and a log \e level. If the message is not compile-time
  48     disabled, the message is then directed to one or several log \e targets.
  49
  50     A \e stream combines log messages with a single purpose: Debug messages, access logging and so
  51     on. Any number of streams may be defined. There is one predefined default stream called \c
  52     senf::log::Debug. (see: \ref SENF_LOG_DEFINE_STREAM)
  53
  54     The \e area gives information about the source location of the message. Areas may be defined and
  55     assigned arbitrarily but should be used to label messages from a single class or subsystem. It
  56     is possible to reuse a class as it's own area tag, which is often desireable.  There is a
  57     default area \c senf::log::DefaultArea which is used, when no other area is assigned. (see: \ref
  58     SENF_LOG_DEFINE_AREA, \ref SENF_LOG_CLASS_AREA)
  59
  60     The log \e level gives information on the importance of the message. The list of log-levels is
  61     fixed. (see: \ref loglevels)
  62
  63     Depending on their the \e stream, \e area and \e level information, log messages can be enabled
  64     or disabled at \e compile time. Messages disabled at compile time should not generate any
  65     code. (see: \ref SENF_LOG_CONF)
  66
  67     \attention The default log stream senf::log::Debug has senf::log::VERBOSE messages
  68         <em>disabled</em> at compile time. senf::log::VERBOSE message will therefore only appear,
  69         if you explictly enable the messages for the area in question using (here for the area
  70         <code>some::Area</code>)
  71         <pre>
  72         g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug), (some)(Area), VERBOSE ))"
  73         </pre>
  74         in addition to routing the messages at runtime. For more, see \ref config.
  75
  76     To be of any use, the log messages have to be written somewhere. This is the responsibility of
  77     any number of \e targets. A \e target receives messages and using it's routing information
  78     decides, wether the message is output or not. A message may be routed to multiple targets
  79     simultaneously or may not be output by any target at all. (see: \ref targets)
  80
  81     \section logging_tutorial Tutorial introduction
  82
  83     Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
  84     some other helpers used to simplify specifying parameters.
  85
  86     \code
  87     namespace foo {
  88
  89         // Define a new log stream with default level, runtime limit and compile time limit
  90         // set to senf::log::MESSAGE
  91         SENF_LOG_DEFINE_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
  92
  93         class Froblizer
  94         {
  95             // Define a log area which will automatically be used by all members of this class.
  96             // This is a combination of SENF_LOG_DEFINE_AREA and SENF_LOG_DEFAULT_AREA.
  97             SENF_LOG_CLASS_AREA();
  98
  99             // Set default log parameters for this scope.
 100             SENF_LOG_DEFAULT_STREAM(foo::UserLog);
 101             SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
 102
 103             // Define an alias for emergency debug messages
 104             // The log area is inherited from the default at the place, where this
 105             // alias is used *not* where it is defined
 106             SENF_LOG_DEFINE_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
 107
 108             void test();
 109
 110         public:
 111             void froblize();
 112         };
 113     }
 114
 115     void foo::Froblizer::froblize()
 116     {
 117         SENF_LOG(("This is the UserLog at level NOTICE in the FroblizeArea"));
 118         SENF_LOG((senf::log::IMPORTANT) ("Same stream and area but at important level"));
 119         SENF_LOG((LogEmerg) ("This goes to the DebugLog at level CRITICAL in the FroblizerArea"));
 120     }
 121
 122     void foo::Froblizer::test()
 123     {
 124         // Change the default log level for this method. stream and area are taken
 125         // from the next scope up
 126         SENF_LOG_DEFAULT_LEVEL(senf::log::VERBOSE);
 127
 128         SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
 129     }
 130
 131     int main(int, char **)
 132     {
 133         // Set up the routing targets
 134         senf::log::ConsoleTarget & console (senf::log::ConsoleTarget::instance());
 135         senf::log::FileTarget logfile ("my.log");
 136
 137         // Debug messages go to the console
 138         console.route<senf::log::Debug>();
 139         // Important user message are written to the log file
 140         logfile.route<foo::UserLog, senf::log::IMPORTANT>();
 141     }
 142     \endcode
 143
 144     \implementation I would have much preferred a more C++ like implementation. However given the
 145         design goals
 146         \li Flexible configuration at compile and runtime
 147         \li Concise usage and simple interface
 148         \li Zero overhead for compile-time disabled log messages
 149
 150         I did not find any non-mcaro implementation which was not either completely convoluted,
 151         unusable or slow. So I turned to a macro based implementation which can provide all the
 152         design goals stated above.
 153  */
 154
 155 \f
 156 // Local Variables:
 157 // mode: c++
 158 // fill-column: 100
 159 // comment-column: 40
 160 // c-file-style: "senf"
 161 // indent-tabs-mode: nil
 162 // ispell-local-dictionary: "american"
 163 // compile-command: "scons -u test"
 164 // mode: flyspell
 165 // mode: auto-fill
 166 // End: