AnCH logger library documentation

Table of Contents

• Introduction
• Prerequisites
• Installation
• Usage
  • Configuration file
    • Writers
    • Categories
• Example

Introduction

AnCH logger library aims to provide facilities for applications logging.

Prerequisites

• boost library (until standard C++ library implements regular expression)
• pthread library
• anch-resource library
• anch-date library

Installation

TODO fill this section

Usage

The library is used in a similar way that log4j. So the classes which will be used are LoggerFactory to initialize and retrieve logger instances and Logger to log messages.
Messages are logged with level which can be (from the lowest to the highest):

• TRACE
• DEBUG
• INFO
• WARN
• ERROR
• FATAL

Each level has a method in Logger class which is named like level in lower case. These methods take a variable number of arguments which have to have stream injection operator definition.

User can define several writers to log messages in separate files and console. Three writer types are available:

• Low priority writer: writer maintains a message queue which will be dequeued in another thread to avoid loosing time in writing files. This writer should be used with an high logging level to avoid to increase memory usage. This writer is thread safe.
• Thread safe writer: writer is access with mutex to avoid concurrent access. This is the default writer.
• Basic writer: writer which is not thread safe.

Loggers are defined by category. They are retrieved if the logger name starts with category. Categories are associated with writers and minimum logging level.

AnCH logger library has to be initialized by calling ANCH_LOGGER_INIT macro.

Configuration file

AnCH logger configuration file is anch-logger.conf in the execution directory. You can defined another configuration file by defining _ANCH_LOGGER_CONFIG_FILE_ variable.

The file has to defined some writers and loggers (see sections below).
Global configuration variables which can be set are:

• low.priority : use low priority writers which will write messages in other threads. Possible value: 0 or 1 . Default to 0 . The value can be override by writers.
• thread.safe : writers are protected against concurrent access. Possible value: 0 or 1 . Default to 1 . The value can be override by writers.

Writers

Writers are declared in [WRITER::<writer>] section.
[WRITER::console] is a predefined writer which log messages in std::cout . The only configuration value for console is writer.pattern .

Configuration values for writters are:

• writer.pattern : pattern for message formatting. Formatting values:
  • %c : the category (logger name).
  • %p : the level.
  • %m : the message.
  • %t : the thread identifier.
  • %d{date_format} : the date (using C++ date formatter).
  • %D{date_format} : the date (using anch-date formatter with high precision clock).
  • Characters to print.
• writer.filepath : log file path.
• writer.max.size : the maximum log file size. Optional. Possible value: number + 'K', 'M' or 'G' (for kilobyte, megabyte and gigabyte).
• writer.max.rotate.index : the maximum number of file to keep. Optional and active only if writer.max.size is set.
• writer.low.priority : use a low priority writer which will write messages in another thread. Possible value: 0 or 1 . Default to 0 .
• writer.thread.safe : writer is protected against concurrent access. Possible value: 0 or 1 . Default to 1 .

Categories

Categories are declared in [CATEGORY::<category>] section.
[CATEGORY::default] is a predefined category which will be used if no other category match the wanted logger.

Configuration values for categories are:

• logger.writers : the writers to use. Possible value: writers list separated by ',' .
• logger.level : the minimum level of messages which will be logged by this logger. Possible value: level in lower case.

Example

Configuration file:

# Use low priority writers
low.priority=1

# std::cout writer
[WRITER::console]
writer.pattern=$d{%Y-%m-%d %H:%M:%S} - $c: $p - $m

# A file writer
[WRITER::test]
writer.filepath=./test.log
writer.pattern=$d{%Y-%m-%d %H:%M:%S} - $c [Thread $t] - $p - $m
writer.max.size=10M
writer.max.rotate.index=9


# Default logger configuration
[CATEGORY::default]
logger.writers=console
logger.level=trace

# Logger configuration for my application
[CATEGORY::org::myapp]
logger.writers=console,test
logger.level=debug

Application code:

#include <iostream>

#include "logger/loggerFactory.hpp"

using std::cout;
using std::endl;

using anch::logger::LoggerFactory;
using anch::logger::Logger;

ANCH_LOGGER_INIT;

int
main(void) {

  const Logger& LOG = LoggerFactory::getLogger("org::myapp::Test"); // Use application logger
  const Logger& DEF_LOG = LoggerFactory::getLogger("XYZ"); // Use default logger

  DEF_LOG.info(_ANCH_LOGGER_CONFIG_FILE_); // Log only in console
  for(int i = 0 ; i < 10 ; i++) {
    LOG.info("Message n° ", i); // Log in console and file
  }

  return 0;
}