qi::log¶

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 Creates and registers the default log handler according to QI_DEFAULT_LOGHANDLER environment variable and compilation flags WITH_SYSTEMD, ANDROID and BOOST_OS_WINDOWS.

Parameters:	verb – Log verbosity level 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)¶

SoftBank Robotics documentation What's new in NAOqi 2.8?

qi::log¶

Summary¶

Detailed Description¶

Encoding¶

Reference¶

Macro¶

Deprecated¶

On this page

SoftBank Robotics documentation What's new in NAOqi 2.8?

Quick search

qi::log¶

Summary¶

Detailed Description¶

Encoding¶

Reference¶

Macro¶

Deprecated¶