/usr/share/doc/libqb-dev/html/qb_log_overview.html is in libqb-doc 1.0.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libqb: Logging</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libqb
 <span id="projectnumber">1.0.1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">index</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Logging </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The logging API provides four main parts (basics, filtering, threading & blackbox).</p>
<p>The idea behind this logging system is not to be prescriptive but to provide a set of tools to help the developer achieve what they want quickly and easily.</p>
<dl class="section user"><dt>Basic logging API.</dt><dd>Call <a class="el" href="qblog_8h.html#ac1dcd0ac044680eead32eae864928d71" title="This is the main function to generate a log message. ">qb_log()</a> to generate a log message. Then to write the message somewhere meaningful call <a class="el" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d" title="Main logging control function. ">qb_log_ctl()</a> to configure the targets.</dd></dl>
<p>Simplest possible use: </p><div class="fragment"><div class="line">main() {</div><div class="line"> <a class="code" href="qblog_8h.html#a4261a1e62a9195139290b15793b8c4bc">qb_log_init</a>(<span class="stringliteral">"simple-log"</span>, LOG_DAEMON, LOG_INFO);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#ac1dcd0ac044680eead32eae864928d71">qb_log</a>(LOG_WARNING, <span class="stringliteral">"watch out"</span>);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#ad6b19c2d1c4de938418820a81d5d622c">qb_log_fini</a>();</div><div class="line">}</div></div><!-- fragment --><dl class="section user"><dt>Configuring log targets.</dt><dd>A log target can be syslog, stderr, the blackbox, stdout, or a text file. By default only syslog is enabled.</dd></dl>
<p>To enable a target do the following: </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa178ee41f37914617d5d86caf651dab5e">QB_LOG_BLACKBOX</a>, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a05b84aca7698c88c32fed66d60821771">QB_LOG_CONF_ENABLED</a>, <a class="code" href="qbdefs_8h.html#aa53d378f26033634af24bd526090073e">QB_TRUE</a>);</div></div><!-- fragment --><p>syslog, stderr, the blackbox, and stdout are static (they don't need to be created, just enabled or disabled). However you can open multiple logfiles (QB_LOG_TARGET_MAX - QB_LOG_TARGET_STATIC_MAX). To do this, use the following code: </p><div class="fragment"><div class="line">mytarget = <a class="code" href="qblog_8h.html#a46abb926947f450d5d66255ffd13ef4f">qb_log_file_open</a>(<span class="stringliteral">"/var/log/mylogfile"</span>);</div><div class="line"><a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(mytarget, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a05b84aca7698c88c32fed66d60821771">QB_LOG_CONF_ENABLED</a>, <a class="code" href="qbdefs_8h.html#aa53d378f26033634af24bd526090073e">QB_TRUE</a>);</div></div><!-- fragment --><p>Once your targets are enabled/opened you can configure them as follows: Configure the size of blackbox </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa178ee41f37914617d5d86caf651dab5e">QB_LOG_BLACKBOX</a>, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a89f358b4a83f94b1efd0e6942506f24d">QB_LOG_CONF_SIZE</a>, 1024*10);</div></div><!-- fragment --><p>Make logging to file threaded: </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(mytarget, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a190db017221bea9bc7c3683ca0dcd023">QB_LOG_CONF_THREADED</a>, <a class="code" href="qbdefs_8h.html#aa53d378f26033634af24bd526090073e">QB_TRUE</a>);</div></div><!-- fragment --><p>To workaround your syslog daemon filtering all messages > LOG_INFO </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa3811428d4ed722d87211411146622ad4">QB_LOG_SYSLOG</a>, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a9b7cdd1040ac89368d7d10c3caa65c2d">QB_LOG_CONF_PRIORITY_BUMP</a>,</div><div class="line"> LOG_INFO - LOG_DEBUG);</div></div><!-- fragment --><p>To ensure all logs to file targets are fsync'ed (default QB_FALSE) </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(mytarget, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5abdebc9d9e19cfa3fa4afd5f744260301">QB_LOG_CONF_FILE_SYNC</a>, <a class="code" href="qbdefs_8h.html#aa53d378f26033634af24bd526090073e">QB_TRUE</a>);</div></div><!-- fragment --><dl class="section user"><dt>Filtering messages.</dt><dd>To have more power over what log messages go to which target you can apply filters to the targets. What happens is the desired callsites have the correct bit set. Then when the log message is generated it gets sent to the targets based on which bit is set in the callsite's "target" bitmap. Messages can be filtered based on the:<ol type="1">
<li>filename + priority</li>
<li>function name + priority</li>
<li>format string + priority</li>
</ol>
</dd></dl>
<p>So to make all logs from evil_function() go to stderr, do the following: </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#a687531ff2f457ea5fe63dc91f74be783">qb_log_filter_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa7667606d44f7b11302762237dff2b8ad">QB_LOG_STDERR</a>, <a class="code" href="qblog_8h.html#a0bcfbbefc6d73b62e72b135ff29fe03faaae48ba27a8dafc2163aaf9637d5ce2f">QB_LOG_FILTER_ADD</a>,</div><div class="line"> <a class="code" href="qblog_8h.html#aa23b899fd898c0c999357532f187fc0fa8991c590b0aa0c3179a8512fbdae9509">QB_LOG_FILTER_FUNCTION</a>, <span class="stringliteral">"evil_function"</span>, <a class="code" href="qblog_8h.html#af7abc145380f1916838e42f9272aa0f6">LOG_TRACE</a>);</div></div><!-- fragment --><p>So to make all logs from totem* (with a priority <= LOG_INFO) go to stderr, do the following: </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#a687531ff2f457ea5fe63dc91f74be783">qb_log_filter_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa7667606d44f7b11302762237dff2b8ad">QB_LOG_STDERR</a>, <a class="code" href="qblog_8h.html#a0bcfbbefc6d73b62e72b135ff29fe03faaae48ba27a8dafc2163aaf9637d5ce2f">QB_LOG_FILTER_ADD</a>,</div><div class="line"> <a class="code" href="qblog_8h.html#aa23b899fd898c0c999357532f187fc0fa868c37c795816ee3d64143c4090afbb6">QB_LOG_FILTER_FILE</a>, <span class="stringliteral">"totem"</span>, LOG_INFO);</div></div><!-- fragment --><p>So to make all logs with the substring "ringbuffer" go to stderr, do the following: </p><div class="fragment"><div class="line"><a class="code" href="qblog_8h.html#a687531ff2f457ea5fe63dc91f74be783">qb_log_filter_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa7667606d44f7b11302762237dff2b8ad">QB_LOG_STDERR</a>, <a class="code" href="qblog_8h.html#a0bcfbbefc6d73b62e72b135ff29fe03faaae48ba27a8dafc2163aaf9637d5ce2f">QB_LOG_FILTER_ADD</a>,</div><div class="line"> <a class="code" href="qblog_8h.html#aa23b899fd898c0c999357532f187fc0faa12df6f8f73d22379661a8f94d69850f">QB_LOG_FILTER_FORMAT</a>, <span class="stringliteral">"ringbuffer"</span>, <a class="code" href="qblog_8h.html#af7abc145380f1916838e42f9272aa0f6">LOG_TRACE</a>);</div></div><!-- fragment --><dl class="section user"><dt>Thread safe non-blocking logging.</dt><dd>Logging is only thread safe when threaded logging is in use. If you plan on logging from multiple threads, you must initialize libqb's logger thread and use qb_log_filter_ctl to set the QB_LOG_CONF_THREADED flag on all the logging targets in use.</dd></dl>
<p>To achieve non-blocking logging, so that any calls to write() or syslog() will not hold up your program, you can use threaded logging as well.</p>
<p>Threaded logging use: </p><div class="fragment"><div class="line">main() {</div><div class="line"> <a class="code" href="qblog_8h.html#a4261a1e62a9195139290b15793b8c4bc">qb_log_init</a>(<span class="stringliteral">"simple-log"</span>, LOG_DAEMON, LOG_INFO);</div><div class="line"> <a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa3811428d4ed722d87211411146622ad4">QB_LOG_SYSLOG</a>, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a190db017221bea9bc7c3683ca0dcd023">QB_LOG_CONF_THREADED</a>, <a class="code" href="qbdefs_8h.html#aa53d378f26033634af24bd526090073e">QB_TRUE</a>);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> daemonize();</div><div class="line"> <span class="comment">// call this after you fork()</span></div><div class="line"> <a class="code" href="qblog_8h.html#aa93049df374b16e48e352327d02be156">qb_log_thread_start</a>();</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#ac1dcd0ac044680eead32eae864928d71">qb_log</a>(LOG_WARNING, <span class="stringliteral">"watch out"</span>);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#ad6b19c2d1c4de938418820a81d5d622c">qb_log_fini</a>();</div><div class="line">}</div></div><!-- fragment --><dl class="section user"><dt>A blackbox for in-field diagnosis.</dt><dd>This stores log messages in a ringbuffer so they can be written to file if the program crashes (you will need to catch SIGSEGV). These can then be easily printed out later.</dd></dl>
<dl class="section note"><dt>Note</dt><dd>the blackbox is not enabled by default.</dd></dl>
<p>Blackbox usage: </p><div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> sigsegv_handler(<span class="keywordtype">int</span> sig)</div><div class="line">{</div><div class="line"> (void)signal (SIGSEGV, SIG_DFL);</div><div class="line"> <a class="code" href="qblog_8h.html#aeb2f3aaaa5c32b994e0dc9069bb50ce6">qb_log_blackbox_write_to_file</a>(<span class="stringliteral">"simple-log.fdata"</span>);</div><div class="line"> <a class="code" href="qblog_8h.html#ad6b19c2d1c4de938418820a81d5d622c">qb_log_fini</a>();</div><div class="line"> <span class="keyword">raise</span>(SIGSEGV);</div><div class="line">}</div><div class="line"></div><div class="line">main() {</div><div class="line"></div><div class="line"> signal(SIGSEGV, sigsegv_handler);</div><div class="line"></div><div class="line"> <a class="code" href="qblog_8h.html#a4261a1e62a9195139290b15793b8c4bc">qb_log_init</a>(<span class="stringliteral">"simple-log"</span>, LOG_DAEMON, LOG_INFO);</div><div class="line"> <a class="code" href="qblog_8h.html#a687531ff2f457ea5fe63dc91f74be783">qb_log_filter_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa178ee41f37914617d5d86caf651dab5e">QB_LOG_BLACKBOX</a>, <a class="code" href="qblog_8h.html#a0bcfbbefc6d73b62e72b135ff29fe03faaae48ba27a8dafc2163aaf9637d5ce2f">QB_LOG_FILTER_ADD</a>,</div><div class="line"> <a class="code" href="qblog_8h.html#aa23b899fd898c0c999357532f187fc0fa868c37c795816ee3d64143c4090afbb6">QB_LOG_FILTER_FILE</a>, <span class="stringliteral">"*"</span>, LOG_DEBUG);</div><div class="line"> <a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa178ee41f37914617d5d86caf651dab5e">QB_LOG_BLACKBOX</a>, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a89f358b4a83f94b1efd0e6942506f24d">QB_LOG_CONF_SIZE</a>, 1024*10);</div><div class="line"> <a class="code" href="qblog_8h.html#ab19da4babdb23834a25e5865016fb02d">qb_log_ctl</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa178ee41f37914617d5d86caf651dab5e">QB_LOG_BLACKBOX</a>, <a class="code" href="qblog_8h.html#aaa6a5dea031c8dc88fbd6d38fd72dee5a05b84aca7698c88c32fed66d60821771">QB_LOG_CONF_ENABLED</a>, <a class="code" href="qbdefs_8h.html#aa53d378f26033634af24bd526090073e">QB_TRUE</a>);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#ac1dcd0ac044680eead32eae864928d71">qb_log</a>(LOG_WARNING, <span class="stringliteral">"watch out"</span>);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#ad6b19c2d1c4de938418820a81d5d622c">qb_log_fini</a>();</div><div class="line">}</div></div><!-- fragment --><dl class="section user"><dt>Tagging messages.</dt><dd>You can tag messages using the second argument to <a class="el" href="qblog_8h.html#a4d29d79cd6bd07e06da9fb56251922f9" title="This is the function to generate a log message if you want to manually add tags. ">qb_logt()</a> or by using <a class="el" href="qblog_8h.html#a687531ff2f457ea5fe63dc91f74be783" title="This allows you modify the 'tags' and 'targets' callsite fields at runtime. ">qb_log_filter_ctl()</a>. This can be used to add feature or sub-system information to the logs.</dd></dl>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* my_tags_stringify(uint32_t <a class="code" href="qblog_8h.html#ac3fc73ca2f0f032be6ea70f9e9cb8837">tags</a>) {</div><div class="line"> <span class="keywordflow">if</span> (<a class="code" href="qbdefs_8h.html#a429078697a3e130797201e1377bd3fdf">qb_bit_is_set</a>(tags, <a class="code" href="qblog_8h.html#ac357216b86a3fb153c6422c2a44eb0ee">QB_LOG_TAG_LIBQB_MSG_BIT</a>) {</div><div class="line"> <span class="keywordflow">return</span> <span class="stringliteral">"libqb"</span>;</div><div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (tags == 3) {</div><div class="line"> <span class="keywordflow">return</span> <span class="stringliteral">"three"</span>;</div><div class="line"> } <span class="keywordflow">else</span> {</div><div class="line"> <span class="keywordflow">return</span> <span class="stringliteral">"MAIN"</span>;</div><div class="line"> }</div><div class="line">}</div><div class="line">main() {</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#a84d94e1a167006c7f69407a56db18291">qb_log_tags_stringify_fn_set</a>(my_tags_stringify);</div><div class="line"> <a class="code" href="qblog_8h.html#a0e8cf298ff5fd224a16537b30a899df9">qb_log_format_set</a>(<a class="code" href="qblog_8h.html#a461cac884ce0c9a80f069af15c6c046aa7667606d44f7b11302762237dff2b8ad">QB_LOG_STDERR</a>, <span class="stringliteral">"[%5g] %p %b"</span>);</div><div class="line"> <span class="comment">// ...</span></div><div class="line"> <a class="code" href="qblog_8h.html#a4d29d79cd6bd07e06da9fb56251922f9">qb_logt</a>(LOG_INFO, 3, <span class="stringliteral">"hello"</span>);</div><div class="line"> <a class="code" href="qblog_8h.html#a4d29d79cd6bd07e06da9fb56251922f9">qb_logt</a>(LOG_INFO, 0, <span class="stringliteral">"hello"</span>);</div><div class="line">}</div></div><!-- fragment --><p> The code above will produce: </p><div class="fragment"><div class="line">[libqb] some message</div><div class="line">[three] info hello</div><div class="line">[MAIN ] info hello</div></div><!-- fragment --> <dl class="section see"><dt>See also</dt><dd><a class="el" href="qblog_8h.html" title="The logging API provides four main parts (basics, filtering, threading & blackbox). ">qblog.h</a> </dd></dl>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.12
</small></address>
</body>
</html>
|