Nulidex Logger Documentation - Logger for C++

WHERE TO DOWNLOAD

The project is available on SourceForge for download. The code is developed on Linux and tested against a version of Microsoft Visual Studio compiler.

SYNOPSIS

Create a logging object:

 logger log("test.log", logger::log_debug, "MAIN LOGGER");

Log something:

 log.warning("I am awesome");

DESCRIPTION

This logging utility is a simple and light logger, yet it offers some "toys", such as the ability to log the file and line name, redirect output to screen, shop for groceries, be your personal bodyguard, and more.

INITIALIZING A LOGGER

Constructor

The constructor accepts three parameters:

 logger log("test.log", logger::log_warn, "MAIN LOGGER");

Here is what this does:

  1. Logs to file named "test.log"
  2. Logs ONLY messages that are at warning or above
  3. OPTIONALLY marks each log line with the string "MAIN LOGGER", but this is only useful when multiple loggers/threads log to the same file.

The log levels are as follows:

  1. log_none - No logging.
  2. log_all - Go crazy. Technically the same as log_debug.
  3. log_debug - Log debug messages and above.
  4. log_info - Log info messages and above.
  5. log_warning - Log warning messages and above.
  6. log_error - Log error messages and above.
  7. log_fatal - Log only fatal messages. This would normally be the only and the last message in your application, if it ever happens. But it won't, because you are an amazing coder. You are welcome.

And, Andrei, why would you even use the log_none level? That looks useless!

At first glance, yes - but not really. Assume you have the same application in development, QA, and production. You don't want any logging in production, for performance reasons, or maybe the production file system is read-only. This allows you to programmatically disable logging depending on the application environment.

How to create multiple application environments is left to the reader as a exercise.

Redirect Options

You can configure the logger to redirect certain log messages to stream, together with logging to a file:

 log.options.debug.p_stream_target = &std::cout;

This property is of type std::ostream *, and it can be anything you like, as long as it's not my soup!

There is an options structure for each log level.

USING THE LOGGER

Logging with levels

This is the simples part of this document:

 log.debug( "debug" );
 log.info( "info" );
 log.warning( "warning" );
 log.error( "error" );
 log.fatal( "mama mia" );

Logging the source code file

The second optional parameter to any log function is the file name of where the logging function originates. You DO NOT have to hard-coded this - leave the job to the C++ pre-processor:

 log.error( "error", __FILE__ );

Logging the source code line

This is the third optional parameter to any of the logging functions. We use the pre-processor to substitute the line number for us:

 log.error( "error", __FILE__, __LINE__ );

MULTI-THREADING

This is actually the original purpose of this logger - to allow multiple client threads to log to the same file, without tripping over each other. The logging class keeps a global map of locks for each individual file name, so if two or more loggers are used in more than one thread to log to the same file, they will share the locks for each file, and politely ask for permission to log. Use this sparingly, since in high-load applications that may become a problem. This is best used for development.

AUTHOR

Andrei Taranchenko

LICENSE

  Nulidex Logger: Logging class for C++
  Copyright (C) 2009 Andrei Taranchenko

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.
 
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.