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     Log messages are arbitrarily created throughout the code using simple log statements (which are
  41     macros). Besides the log message itself, every log message is labeled with additional
  42     information: The \e stream, the \e area and a log \e level. If the message is not compile-time
  43     disabled, the message is then directed to one of several log \e targets.
  44
  45     A \e stream combines log messages with a single purpose: Debug messages, access logging and so
  46     on. Any number of streams may be defined. There is one predefined default stream called \c
  47     senf::log::Debug. (see: \ref SENF_LOG_DEF_STREAM)
  48
  49     The \e area gives information about the source location of the message. Areas may be defined and
  50     assigned arbitrarily but should be used to label messages from a single class or subsystem. It
  51     is possible to reuse a class as it's own area tag, which is often desireable.  (see: \ref
  52     SENF_LOG_DEF_AREA, \ref SENF_LOG_CLASS_AREA)
  53
  54     The log \e level gives information on the importance of the message. The list of log-levels is
  55     fixed. (see: \ref loglevels)
  56
  57     Depending on their the \e stream, \e area and \e level information, log messages can be enabled
  58     or disabled at \e compile time. Messages disabled at compile time should not generate any
  59     code. (see: \ref SENF_LOG_CONF)
  60
  61     To be of any use, the log messages have to be written somewhere. This is the responsibility of
  62     any number of \e targets. A \e target receives messages and using it's routing information
  63     decides, wether the message is output or not. A message may be routed to multiple targets
  64     simultaneously or may not be output by any target at all. (see: \ref targets)
  65
  66     \section logging_tutorial Tutorial introduction
  67
  68     Using the logging library mostly concerns using \ref SENF_LOG statements in your code. There are
  69     some other helpers used to simplify specifying parameters.
  70
  71     \code
  72     namespace foo {
  73
  74         // Define a new log stream with default level, runtime limit and compile time limit
  75         // set to senf::log::MESSAGE
  76         SENF_LOG_DEF_STREAM( UserLog, senf::log::MESSAGE, senf::log::MESSAGE, senf::log::MESSAGE );
  77
  78         class Froblizer
  79         {
  80             // Define a log area which will automatically be used by all members of this class.
  81             // This is a combination of SENF_LOG_DEF_AREA and SENF_LOG_DEFAULT_AREA.
  82             SENF_LOG_CLASS_AREA();
  83
  84             // Set default log parameters for this scope.
  85             SENF_LOG_DEFAULT_STREAM(foo::UserLog);
  86             SENF_LOG_DEFAULT_LEVEL(senf::log::NOTICE);
  87
  88             // Define an alias for emergency debug messages
  89             // The log area is inherited from the default at the place, where this
  90             // alias is used *not* where it is defined
  91             SENF_LOG_DEF_ALIAS(LogEmerg, (senf::log::Debug)(senf::log::CRITICAL));
  92
  93             void test();
  94
  95         public:
  96             void froblize();
  97         };
  98     }
  99
 100     void foo::Froblizer::froblize()
 101     {
 102         SENF_LOG(("This is the UserLog at level NOTICE in the FroblizeArea"));
 103         SENF_LOG((senf::log::WARNING) ("Same stream and area but at warning level"));
 104         SENF_LOG((LogEmerg) ("This goes to the DebugLog at level CRITICAL in the FroblizerArea"));
 105     }
 106
 107     void foo::Froblizer::test()
 108     {
 109         // Change the default log level for this method. stream and area are taken
 110         // from the next scope up
 111         SENF_LOG_DEFAULT_LEVEL(senf::log::VERBOSE);
 112
 113         SENF_LOG(("Log to UserLog stream in Froblizer area however at VERBOSE level"));
 114     }
 115
 116     int main(int, char **)
 117     {
 118         // Set up the routing targets
 119         senf::log::ConsoleTarget console;
 120         senf::log::FileTarget logfile ("my.log");
 121
 122         // Debug messages go to the console
 123         console.route<senf::log::Debug>();
 124         // Important user message are written to the log file
 125         logfile.route<foo::UserLog, senf::log::IMPORTANT>();
 126     }
 127     \endcode
 128
 129     \implementation I would have much preferred a more C++ like implementation. However given the
 130         design goals
 131         \li Flexible configuration at compile and runtime
 132         \li Concise usage and simple interface
 133         \li Zero overhead for compile-time disabled log messages
 134
 135         I did not find any non-mcaro implementation which was not either completely convoluted,
 136         unusable or slow. So I turned to a macro based implementation which can provide all the
 137         design goals stated above.
 138  */
 139
 140 \f
 141 // Local Variables:
 142 // mode: c++
 143 // fill-column: 100
 144 // comment-column: 40
 145 // c-file-style: "senf"
 146 // indent-tabs-mode: nil
 147 // ispell-local-dictionary: "american"
 148 // compile-command: "scons -u test"
 149 // mode: flyspell
 150 // mode: auto-fill
 151 // End: