/** \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<AreaRegistry>
public:
typedef boost::transform_iterator<SelectName, Registry::const_iterator> iterator;
+ ///< Iterator type
# ifdef DOXYGEN
// Hmm ... doxygen does not understand using declarations ...
using senf::singleton<AreaRegistry>::instance;
- iterator begin();
- iterator end();
+ iterator begin(); ///< Beginning of area name sequence
+ iterator end(); ///< End of area name sequence
private:
AreaRegistry();
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:
+ <pre>
+ g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
+ (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
+ (( (foo)(Transactions),(_),NOTICE ))" ...
+ </pre>
+ 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<senf::log::Debug>();
+ consoleLog.route<foo::Transactions, foo::SomeClass>(senf::log::Target::REJECT);
+ consoleLog.route<foo::Transactions, senf::log::IMPORTANT>();
+
+ fileLog.route<foo::Transactions>();
+ \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 {
/** \brief Compile time configuration
This define symbol sets the compile time logger configuration. This symbol should normally
- be set on the compiler command line:
- <pre>
- g++ ... -DSENF_LOG_CONF="(( (senf)(log)(Debug),(_),DISABLED ))
- (( (senf)(log)(Debug),(foo)(SomeClass),VERBOSE ))
- (( (foo)(Transactions),(_),NOTICE ))" ...
- </pre>
- (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:
\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
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 <em>log stream</em>,
\li the <em>log area</em>,
\li the <em>log level</em>,
- \li and the log message itself
- These parameters may be specified <i>in arbitrary order</i> 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 <i>in arbitrary order</i> (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
\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
projects / senf.git / commitdiff