Logging Options

• General
• Writing Log Messages
• Invoking Logging Arguments
  • Command Line
  • Config File
• Logfiles

General

We use our own logging mechanism which is provided as part of the MaidSafe-Common library. It makes use of Boost.Program_options to handle command line arguments and use of an ini file to set the logging parameters.

At the moment, logging statements are compiled out in Release mode, although we are considering allowing Release mode logging, assuming this does not significantly impact performance and does not leak any security information whatsoever.

Writing Log Messages

To enable logging in a file you are working on, simply

#include "maidsafe/common/log.h"

Then use log statements as you would a std::cout statement, e.g.

LOG(kInfo) << some_var << "more info";

Note that each message will have a \n appended.

The LOG(...) macro currently accepts one of six levels (in ascending order): kVerbose, kInfo, kSuccess, kWarning, kError, or kAlways. When running the executable with logging enabled, you can choose the required level, and all log messages at or above that level will be displayed.

Every log message will have the following format:

E 5560  00:24:48.596129 common/crypto.h:210] Log message
|     \          \             |         |
level  thread ID  timestamp   file   line number

Logging is threadsafe and is done asynchronously by default. This means that adding LOG statements has less of an effect on speed of execution than using std::cout. Messages are held in a FIFO queue to maintain their correct chronological order. Asynchronous logging can be undesirable if stepping over code in a debugger. If you wish to see the log message output to console as the LOG statement is stepped over, you can disable asynchronous logging.

Invoking Logging Arguments

Arguments can be passed on the command line or via a config file. If both are used, the command line arguments take precedence.

Command Line

Argument	Description
-h --help	Show help message.
--log_no_async	Disable asynchronous logging.
--log_colour_mode arg	0 for no colour, 1 for partial, 2 full. Default mode is 1.
--log_config arg	Path to the logging configuration file.
--log_no_console	Disable logging to console.
--log_<project> level	Set log level for <project>.
--log_* level	Set log level for all projects. Overrides any individual project levels.
--log_folder arg	Path to folder where log files will be written. Default value is <system temp dir>/maidsafe_logs. If arg is "", no files will be written.

Logging levels are Verbose, Info, Success, Warning, Error, and Always. You can use just the initial letter, and these are all case-insensitive.

For example:

./TESTencrypt --log_folder ./logs --log_common w --log_encrypt Info

will create the folder ./logs if it doesn't already exist and write logfiles there. It will output asynchronously. Only Warning level and above from MaidSafe-Common and Info level and above from MaidSafe-Encrpyt will be output.

Config File

The main benefit of the config file is obviously that it is persistent. The default search location of the config file is <system temp dir>/maidsafe_log.ini. You can pass the path to a different config file using the --log_config argument (see above).

There is an example config file called maidsafe_log.ini in the root of MaidSafe. Just copy this wherever you want and uncomment any options you want on/off by default. Any options set this way will be overridden by a corresponding command line option.

Logfiles

By default, logfiles are written to <system temp dir>/maidsafe_logs. You can specify a different path to a folder which will be created if necessary. If you don't want logfiles to be written, specify --log_folder "".

There will be a logfile created for every project which has a log level specified. Such a logfile will contain logging only for that project, along with any gtest output. There will also be a combined logfile if you have 0 or >1 projects specified. This will contain all the logging (as we currently see it in the console).

If you use the --log_* option to specify the same log level for all projects, this is equivalent to specifying every project's level as that, i.e. you'll end up with 12 logfiles.

The logfiles' names include a timestamp, so subsequent runs shouldn't obliterate previous logfiles.