qi::log

Detailed Description

qi::log provides logging facilities. It allows one to log in different categories with different levels.

The user can choose which categories they want to see and at which level. It is possible to add handlers to process the log, broadcast them on the network, save them in a file, etc.

Encoding

Logs are not modified when printed or transmitted.

That means that if the source file is UTF-8 AND the compiler considers your string literals as UTF-8 AND the output handles UTF-8 then all logs are printed the same.

Warning

On Windows, the compiler (VS-2013) won’t necessarily interpret string literals as UTF-8. Most of the time with special characters, the behavior is undefined.

#include <qi/log.hpp>

qiLogCategory("myprogram.mymodule");

int main()
{
  qiLogInfo() << "Hello world";

  // this variant is slower than the one above
  qiLogError("this.goes.in.another.category") << "Goodbye world";

  return 0;
}

Warning

Log calls are lazily evaluated. When you put a function call in your log statements, the function will not be called if the log is disabled (at runtime or compilation-time).

int i = 0;

int f() { ++i; return 0; }

void g() {
  qiLogVerbose() << f(); // f() may not be called!
}

Reference

Macro

qiLogCategory(Cat)

Add default category for the current scope. Each log has a category defined by the call to qiLogCategory() found in scope. So you must call qiLogCategory() at least once, for instance at the beginning of your source file or function.

{
  qiLogCategory(my.category);
  qiLogInfoF("1 + 1 is %s", 1+1);
  qiLogInfo() << "1 + 1 is " << 1+1;
}
qiLogDebug(...)

Log in debug mode. Not compiled on release and not shown by default. Use as follow:

qiLogDebug("foo.bar", "my foo is %d bar", 42);
// or
qiLogDebug("foo.bar") << "my foo is " << 42 << "bar";

If you don’t want to see any log, use silent log level.

qiLogDebugF(Msg, ...)
qiLogVerbose(...)

Log in verbose mode. This level is not shown by default.

qiLogVerboseF(Msg, ...)
qiLogInfo(...)

Log in info mode.

qiLogInfoF(Msg, ...)
qiLogWarning(...)

Log in warning mode.

qiLogWarningF(Msg, ...)
qiLogError(...)

Log in error mode.

qiLogErrorF(Msg, ...)
qiLogFatal(...)

Log in fatal mode.

qiLogFatalF(Msg, ...)
enum qi::LogColor

Brief: Logs color mode.

Name Brief
LogColor_Never Never show color.
LogColor_Auto Auto color.
LogColor_Always Always show color.
enum qi::LogContextAttr

Brief: Logs context attribute.

Name Value Brief
LogContextAttr_None 0 No context.
LogContextAttr_Verbosity 1 Show logs level.
LogContextAttr_ShortVerbosity 2 Show short logs level.
LogContextAttr_SystemDate 4 Show qi::SystemClock dates.
LogContextAttr_Tid 8 Show threads id.
LogContextAttr_Category 16 Show categories.
LogContextAttr_File 32 Show logs files.
LogContextAttr_Function 64 Show functions name.
LogContextAttr_Return 128 Print an end line between contexts and logs.
LogContextAttr_Date 256 Show qi::Clock dates.
enum qi::LogLevel

Brief: Log level verbosity.

Name Value Brief
LogLevel_Silent 0 silent log level
LogLevel_Fatal fatal log level
LogLevel_Error error log level
LogLevel_Warning warning log level
LogLevel_Info info log level
LogLevel_Verbose verbose log level
LogLevel_Debug debug log level
CategoryType qi::log::addCategory(const std::string& name)

Brief: Add/get a category.

Parameters:
  • name – Category to add/get.
Returns:

CategoryType structure.

void qi::log::addFilter(const std::string& cat, qi::LogLevel level, SubscriberId sub = 0)

Brief: Set per-subscriber category to level. Globbing is supported.

Parameters:
  • cat – Category to set.
  • level – Level to set to the category.
  • sub – Log subscriber id.
 
addFilter("internal.*", silent);

One can also set a filtering rule in QI_LOG_FILTERS environment variable. syntax is colon-separated list of rules of the form (+|-)CAT or CAT=level. For example, -internal.*:file=verbose

void qi::log::addFilters(const std::string& rules, SubscriberId sub = 0)

Brief: Parse and execute a set of verbosity rules.

Parameters:
  • rules – Colon separated of rules. Each rule can be: (+)?CAT : enable category CAT-CAT : disable category CATCAT=level : set category CAT to level
  • sub – Log subscriber id.

Each category can include a ‘*’ for globbing. Can be set with env var QI_LOG_FILTERS. For instance ‘qi.*=debug:-qi.foo:+qi.foo.bar’ stands for “all qi.* logs in debug, remove all qi.foo logs except qi.foo.bar”.

SubscriberId qi::log::addHandler(const std::string& name, qi::log::Handler fct, qi::LogLevel defaultLevel = LogLevel_Info)

Brief: Add a log handler for this process’ logs.

Parameters:
  • name – Name of the handler, useful to remove handler (prefer lowercase).
  • fct – Boost delegate to log handler function.
  • defaultLevel – default log verbosity.
Returns:

New log subscriber id added.

std::vector<std::string> qi::log::categories()

Brief: Get the list of all categories.

Returns:The list of existing categories
LogColor qi::log::color()

Brief: Get log color.

Returns:Returns LogColor enum.
int qi::log::context()

Brief: Get log context.

Returns:Returns the level of context verbosity.
void qi::log::destroy()

Should be called in the main of program using atexit. For example:

atexit(qi::log::destroy)

This is useful only for asynchronous log.

void qi::log::disableCategory(const std::string& cat, SubscriberId sub = 0)

Brief: Set category to silent log level. Globbing is supported.

Parameters:
  • cat – Category to set to silence level.
  • sub – Log subscriber id.
void qi::log::enableCategory(const std::string& cat, SubscriberId sub = 0)

Brief: Set category to current verbosity level. Globbing is supported.

Parameters:
  • cat – Category to set to current verbosity level.
  • sub – Log subscriber id.
void qi::log::flush()

Flush asynchronous logs.

void qi::log::init(qi::LogLevel verb = qi::LogLevel_Info, qi::LogContext context = qi::LogContextAttr_ShortVerbosity|qi::LogContextAttr_Tid|qi::LogContextAttr_Category, bool synchronous = true)

Brief: Initialization of the logging system (could be avoided)

Parameters:
  • verb – Log verbosity
  • context – Display Context
  • synchronous – Synchronous log
bool qi::log::isVisible(CategoryType category, qi::LogLevel level)

Brief: Check if the given combination of category and level is enable.

Parameters:
  • category – Category to check.
  • level – Level associate to category.
Returns:

true if given combination of category and level is enabled.

bool qi::log::isVisible(const std::string& category, qi::LogLevel level)

Brief: Check if the given combination of category and level is enable.

Parameters:
  • category – Category to check.
  • level – Level associate to category.
Returns:

true if given combination of category and level is enabled.

void qi::log::log(const qi::LogLevel verb, CategoryType category, const std::string& msg, const char* file = "", const char* fct = "", const int line = 0)

Brief: Log function. You should call qiLog* macros instead.

Parameters:
  • verb – The verbosity of the message.
  • category – Log category (for filtering).
  • msg – Log message.
  • file – Filename from which this function was called (ex: FILE).
  • fct – Function name from which this function was called (ex: FUNCTION).
  • line – Line from which this function was called (ex: LINE).
void qi::log::log(const qi::LogLevel verb, const char* category, const char* msg, const char* file = "", const char* fct = "", const int line = 0)

Brief: Log function. You should call qiLog* macros instead.

Parameters:
  • verb – The verbosity of the message.
  • category – Log category (for filtering).
  • msg – Log message.
  • file – Filename from which this function was called (ex: FILE).
  • fct – Function name from which this function was called (ex: FUNCTION).
  • line – Line from which this function was called (ex: LINE).
qi::LogLevel qi::log::logLevel(SubscriberId sub = 0)

Brief: Get log verbosity.

Parameters:
  • sub – Log subscriber id.
Returns:

Maximal verbosity displayed.

const char* qi::log::logLevelToString(const qi::LogLevel verb, bool verbose = true)

Brief: Convert log verbosity to a readable string.

Parameters:
  • verb – Verbosity value.
  • verbose – Enable verbose conversion.
Returns:

Returns a string matching the log level verbosity.

void qi::log::removeHandler(const std::string& name)

Brief: Remove a log handler.

Parameters:
  • name – Name of the handler.
void qi::log::setColor(LogColor color)

Brief: Set log color.

Parameters:
  • color – Log color value.
void qi::log::setContext(int ctx)

Brief: Set log context verbosity.

Parameters:
  • ctx – Value to set context.

Show context logs, it’s a bit field (add the values below).

Context values possible: 1 : Verbosity2 : ShortVerbosity4 : Date8 : ThreadId16 : Category32 : File64 : Function128: EndOfLine some useful values for context are:26 : (verb+threadId+cat)30 : (verb+threadId+date+cat)126: (verb+threadId+date+cat+file+fun)254: (verb+threadId+date+cat+file+fun+eol)

Can be set with env var QI_LOG_CONTEXT

void qi::log::setSynchronousLog(bool sync)

Brief: Enables or disables synchronous logs.

Parameters:
  • sync – Value to set or unset synchronous.

When setting to async, this function must be called after main has started.

void qi::log::setLogLevel(const qi::LogLevel lv, SubscriberId sub = 0)

Brief: Set log Level.

Parameters:
  • lv – Default verbosity level shown in the logs.
  • sub – Log subscriber id.

Levels set by this function is a default value, overriden by all addFilter() and addFilters() calls.

Change the log minimum level: [0-6] (default:4): 0: silent1: fatal2: error3: warning4: info5: verbose6: debug

Can be set with env var QI_LOG_LEVEL.

If you don’t want any log use silent mode.

qi::LogLevel qi::log::stringToLogLevel(const char* verb)

Brief: Convert string to log verbosity.

Parameters:
  • verb – debug, verbose, info, warning, error, fatal, silent
Returns:

Log level verbosity

Deprecated

void qi::log::setVerbosity(SubscriberId sub, const qi::log::LogLevel lv)

Deprecatedsince 1.22. Use qi::log::setLogLevel(const qi::LogLevel, SubscriberId)

void qi::log::setVerbosity(SubscriberId sub, const qi::log::LogLevel lv)

Deprecatedsince 1.22. Use qi::log::setLogLevel(const qi::LogLevel, SubscriberId)

void qi::log::setVerbosity(SubscriberId sub, const qi::log::LogLevel lv)

Deprecatedsince 1.22. Use qi::log::setLogLevel(const qi::LogLevel, SubscriberId)

void qi::log::setCategory(SubscriberId sub, const std::string& cat, qi::log::LogLevel level)

Deprecatedsince 1.22. Use qi::log::addFilter(const std::string&, qi::LogLevel, SubscriberId)

void qi::log::setCategory(SubscriberId sub, const std::string& cat, qi::log::LogLevel level)

Deprecatedsince 1.22. Use qi::log::addFilter(const std::string&, qi::LogLevel, SubscriberId)

qi::log::verbosity(SubscriberId)
« qi::IOColor | C++ qi base API | qi helper macros »
« previous | up | next »