libqi-api  2.8.7.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Namespaces | Classes | Typedefs | Functions
qi::log Namespace Reference

Log functions with different levels of verbosity. More...

Namespaces

 detail
 
 env
 

Classes

class  LogStream
 
class  ConsoleLogHandler
 Print colored logs to the console. More...
 
class  CsvLogHandler
 
class  FileLogHandler
 
class  HeadFileLogHandler
 Log the first length lines to a file. . More...
 
class  TailFileLogHandler
 Keeps at most 2 MiB of logs. . More...
 

Typedefs

using CategoryType = detail::Category *
 Catergory Informations. More...
 
using SubscriberId = unsigned int
 Subscriber Identifier. More...
 
typedef unsigned int Subscriber
 
using logFuncHandler = boost::function7< void, const qi::LogLevel, const qi::os::timeval, const char *, const char *, const char *, const char *, int >
 Boost delegate to log function (verbosity lv, date of log, category, message, file, function, line). More...
 
using Handler = boost::function8< void, const qi::LogLevel, const qi::Clock::time_point, const qi::SystemClock::time_point, const char *, const char *, const char *, const char *, int >
 Boost delegate to log function (verbosity lv, dates of log, category, message, file, function, line). More...
 

Functions

bool isVisible (CategoryType category, qi::LogLevel level)
 Check if the given combination of category and level is enable. More...
 
Handler makeAndroidLogHandler ()
 create a log handler which redirect logs to android log system. More...
 
Handler makeJournaldLogHandler ()
 Return a log handler, which forwards logs to systemd's journal. More...
 
void init (qi::LogLevel verb=qi::LogLevel_Info, qi::LogContext context=qi::LogContextAttr_ShortVerbosity|qi::LogContextAttr_Tid|qi::LogContextAttr_Category, bool synchronous=true)
 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. More...
 
void destroy ()
 Stop and flush the logging system. More...
 
void log (const qi::LogLevel verb, const char *category, const char *msg, const char *file="", const char *fct="", const int line=0)
 Log function. You should call qiLog* macros instead. More...
 
void log (const qi::LogLevel verb, CategoryType category, const std::string &msg, const char *file="", const char *fct="", const int line=0)
 Log function. You should call qiLog* macros instead. More...
 
const char * logLevelToString (const qi::LogLevel verb, bool verbose=true)
 Convert log verbosity to a readable string. More...
 
qi::LogLevel stringToLogLevel (const char *verb)
 Convert string to log verbosity. More...
 
void setLogLevel (const qi::LogLevel lv, SubscriberId sub=0)
 Set log Level. More...
 
qi::LogLevel logLevel (SubscriberId sub=0)
 Get log verbosity. More...
 
std::vector< std::string > categories ()
 Get the list of all categories. More...
 
CategoryType addCategory (const std::string &name)
 Add/get a category. More...
 
void enableCategory (const std::string &cat, SubscriberId sub=0)
 Set category to current verbosity level. Globbing is supported. More...
 
void disableCategory (const std::string &cat, SubscriberId sub=0)
 Set category to silent log level. Globbing is supported. More...
 
bool isVisible (const std::string &category, qi::LogLevel level)
 Check if the given combination of category and level is enable. More...
 
void addFilters (const std::string &rules, SubscriberId sub=0)
 Parse and execute a set of verbosity rules. More...
 
void addFilter (const std::string &cat, qi::LogLevel level, SubscriberId sub=0)
 Set per-subscriber category to level. Globbing is supported. More...
 
void setContext (int ctx)
 Set log context verbosity. More...
 
int context ()
 Get log context. More...
 
void setColor (LogColor color)
 Set log color. More...
 
LogColor color ()
 Get log color. More...
 
void setSynchronousLog (bool sync)
 Enables or disables synchronous logs. More...
 
SubscriberId addHandler (const std::string &name, qi::log::Handler fct, qi::LogLevel defaultLevel=LogLevel_Info)
 Add a log handler for this process' logs. More...
 
SubscriberId addLogHandler (const std::string &name, qi::log::logFuncHandler fct, qi::LogLevel defaultLevel=LogLevel_Info)
 Add a log handler. More...
 
void removeHandler (const std::string &name)
 Remove a log handler. More...
 
void removeLogHandler (const std::string &name)
 Remove a log handler. More...
 
void flush ()
 Flush asynchronous logs. More...
 
void setVerbosity (SubscriberId sub, const qi::log::LogLevel lv)
 
void setCategory (SubscriberId sub, const std::string &cat, qi::log::LogLevel level)
 

Detailed Description

Log functions with different levels of verbosity.

Typedef Documentation

Catergory Informations.

Definition at line 224 of file log.hxx.

using qi::log::Handler = typedef boost::function8<void, const qi::LogLevel, const qi::Clock::time_point, const qi::SystemClock::time_point, const char*, const char*, const char*, const char*, int>

Boost delegate to log function (verbosity lv, dates of log, category, message, file, function, line).

Definition at line 243 of file log.hpp.

using qi::log::logFuncHandler = typedef boost::function7<void, const qi::LogLevel, const qi::os::timeval, const char*, const char*, const char*, const char*, int>

Boost delegate to log function (verbosity lv, date of log, category, message, file, function, line).

Deprecated:
1.24 use qi::log::Handler

Definition at line 230 of file log.hpp.

typedef unsigned int qi::log::Subscriber
Deprecated:
1.22 Use qi::log::SubscriberId

Definition at line 216 of file log.hpp.

using qi::log::SubscriberId = typedef unsigned int

Subscriber Identifier.

Definition at line 211 of file log.hpp.

Function Documentation

CategoryType qi::log::addCategory ( const std::string &  name)

Add/get a category.

Parameters
nameCategory to add/get.
Returns
CategoryType structure.
void qi::log::addFilter ( const std::string &  cat,
qi::LogLevel  level,
SubscriberId  sub = 0 
)

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

Parameters
catCategory to set.
levelLevel to set to the category.
subLog subscriber id.
* .. code-block:: cpp
*
*   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 
)

Parse and execute a set of verbosity rules.

Parameters
rulesColon separated of rules. Each rule can be:
  • (+)?CAT : enable category CAT
  • -CAT : disable category CAT
  • CAT=level : set category CAT to level

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".

Parameters
subLog subscriber id.
SubscriberId qi::log::addHandler ( const std::string &  name,
qi::log::Handler  fct,
qi::LogLevel  defaultLevel = LogLevel_Info 
)

Add a log handler for this process' logs.

Warning
Handlers are usually called synchronously, they must not block.
Parameters
nameName of the handler, useful to remove handler (prefer lowercase).
fctBoost delegate to log handler function.
defaultLeveldefault log verbosity.
Returns
New log subscriber id added.
SubscriberId qi::log::addLogHandler ( const std::string &  name,
qi::log::logFuncHandler  fct,
qi::LogLevel  defaultLevel = LogLevel_Info 
)

Add a log handler.

Parameters
nameName of the handler, useful to remove handler (prefer lowercase).
fctBoost delegate to log handler function.
defaultLeveldefault log verbosity.
Returns
New log subscriber id added.
Deprecated:
1.24 use qi::log::addHandler
std::vector<std::string> qi::log::categories ( )

Get the list of all categories.

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

Get log color.

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

Get log context.

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

Stop and flush the logging system.

* Should be called in the main of program using atexit. For example:
*
* .. code-block:: cpp
*
*     atexit(qi::log::destroy)
*
* This is useful only for asynchronous log.
* 
void qi::log::disableCategory ( const std::string &  cat,
SubscriberId  sub = 0 
)

Set category to silent log level. Globbing is supported.

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

Set category to current verbosity level. Globbing is supported.

Parameters
catCategory to set to current verbosity level.
subLog subscriber id.
void qi::log::flush ( )

Flush asynchronous logs.

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
verbLog verbosity level
contextDisplay Context
synchronousSynchronous log
bool qi::log::isVisible ( CategoryType  category,
qi::LogLevel  level 
)
inline

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

Parameters
categoryCategory to check.
levelLevel associate to category.
Returns
true if given combination of category and level is enabled.

Definition at line 219 of file log.hxx.

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

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

Parameters
categoryCategory to check.
levelLevel associate to category.
Returns
true if given combination of category and level is enabled.
void qi::log::log ( const qi::LogLevel  verb,
const char *  category,
const char *  msg,
const char *  file = "",
const char *  fct = "",
const int  line = 0 
)

Log function. You should call qiLog* macros instead.

Parameters
verbThe verbosity of the message.
categoryLog category (for filtering).
msgLog message.
fileFilename from which this function was called (ex: FILE).
fctFunction name from which this function was called (ex: FUNCTION).
lineLine from which this function was called (ex: LINE).
void qi::log::log ( const qi::LogLevel  verb,
CategoryType  category,
const std::string &  msg,
const char *  file = "",
const char *  fct = "",
const int  line = 0 
)

Log function. You should call qiLog* macros instead.

Parameters
verbThe verbosity of the message.
categoryLog category (for filtering).
msgLog message.
fileFilename from which this function was called (ex: FILE).
fctFunction name from which this function was called (ex: FUNCTION).
lineLine from which this function was called (ex: LINE).
qi::LogLevel qi::log::logLevel ( SubscriberId  sub = 0)

Get log verbosity.

Parameters
subLog subscriber id.
Returns
Maximal verbosity displayed.
const char* qi::log::logLevelToString ( const qi::LogLevel  verb,
bool  verbose = true 
)

Convert log verbosity to a readable string.

Parameters
verbVerbosity value.
verboseEnable verbose conversion.
Returns
Returns a string matching the log level verbosity.
Handler qi::log::makeAndroidLogHandler ( )

create a log handler which redirect logs to android log system.

Limitations: timestamps, file name, function name and line number are discarded.

Handler qi::log::makeJournaldLogHandler ( )

Return a log handler, which forwards logs to systemd's journal.

The following journal fields are added:

  • MESSAGE, the log message
  • QI_CATEGORY, the qiLogCategory
  • PRIORITY, with the log level (mapped to syslog priority)
  • QI=1
  • CODE_FILE, CODE_LINE, CODE_FUNC (only when NO_QI_LOG_DETAILED_CONTEXT is not defined)
  • SYSLOG_IDENTIFIER, with the content of the QI_SYSLOG_IDENTIFIER environment variable (only if QI_SYSLOG_IDENTIFIER is defined and not empty).

The returned handler is not thread-safe, which is fine: libqi does not call its log handlers concurrently.

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

Remove a log handler.

Parameters
nameName of the handler.
void qi::log::removeLogHandler ( const std::string &  name)

Remove a log handler.

Parameters
nameName of the handler.
Deprecated:
1.24 use qi::log::removeHandler
void qi::log::setCategory ( SubscriberId  sub,
const std::string &  cat,
qi::log::LogLevel  level 
)
inline
void qi::log::setColor ( LogColor  color)

Set log color.

Parameters
colorLog color value.
void qi::log::setContext ( int  ctx)

Set log context verbosity.

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

Parameters
ctxValue to set context.

Context values possible:

  • 1 : Verbosity
  • 2 : ShortVerbosity
  • 4 : Date
  • 8 : ThreadId
  • 16 : Category
  • 32 : File
  • 64 : Function
  • 128: 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::setLogLevel ( const qi::LogLevel  lv,
SubscriberId  sub = 0 
)

Set log Level.

Parameters
lvDefault verbosity level shown in the logs.
subLog 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: silent
  • 1: fatal
  • 2: error
  • 3: warning
  • 4: info
  • 5: verbose
  • 6: debug

Can be set with env var QI_LOG_LEVEL.

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

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

Enables or disables synchronous logs.

Parameters
syncValue to set or unset synchronous.

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

void qi::log::setVerbosity ( SubscriberId  sub,
const qi::log::LogLevel  lv 
)
inline
qi::LogLevel qi::log::stringToLogLevel ( const char *  verb)

Convert string to log verbosity.

Parameters
verbdebug, verbose, info, warning, error, fatal, silent
Returns
Log level verbosity