# SoftBank Robotics documentation What's new in NAOqi 2.8?

# qi::log

## Summary

Global Namespaces

- namespace qi::log

  Functions (namespace qi::log)

  qi::log::addCategory

  qi::log::color

  qi::log::enableCategory

  qi::log::init

  qi::log::setSynchronousLog

  qi::log::setColor

  qi::log::addHandler

  qi::log::removeHandler

  qi::log::setVerbosity

  qi::log::setLogLevel

  qi::log::verbosity

  qi::log::flush

  qi::log::isVisible

  qi::log::addFilters

  qi::log::context

  qi::log::logLevelToString

  qi::log::logLevel

  qi::log::log

  qi::log::setContext

  qi::log::categories

  qi::log::destroy

  qi::log::disableCategory

  qi::log::stringToLogLevel

  qi::log::setCategory

  qi::log::addFilter

Global Macros

qiLogWarningF

qiLogFatal

qiLogInfo

qiLogCategory

qiLogDebug

qiLogErrorF

qiLogInfoF

qiLogDebugF

qiLogVerbose

qiLogWarning

qiLogVerboseF

qiLogFatalF

qiLogError

## 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 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)

Glossary Site map Index Support Contact Legal Notices