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
|
<!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"/>
<title>libcontextsubscriber: </title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<p>The library (and ContexKit in general) use a simple logging system designed to unify the output and make the debugging easier.</p>
<h2><a class="anchor" id="API">
API</a></h2>
<p>Four types of log messages (presented here in the order of importance) are supported: <b>Test</b>, <b>Debug</b>, <b>Warning</b> and <b>Critical</b>.</p>
<p>The first one, the <b>Test</b> message requires some attention. It's meant to be used from tests and unit-tests to log various stages of the test execution. It'll make the test output more easily filterable.</p>
<p>The log messages can be used like this:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="logging_8h.html#abfb57c8a40821bf0caa9a29a8dfc47b7">contextTest</a>() << <span class="stringliteral">"This is some message"</span>;
<a class="code" href="logging_8h.html#ad9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <span class="stringliteral">"My value is:"</span> << someVariable;
<a class="code" href="logging_8h.html#a63433fe15ab356004ccdd4263b0910c0">contextWarning</a>() << <span class="stringliteral">"Expecting key:"</span> << something.getKey();
<a class="code" href="logging_8h.html#a7f115b5076497bd3af236e8778940ea1">contextCritical</a>() << 5 << <span class="stringliteral">"is bigger than"</span> << 4;
</pre></div><p>Notice that the logging framework (very much like ie <b>qDebug</b>) automatically ads whitespace. So:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="logging_8h.html#ad9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <span class="stringliteral">"My value is"</span> << 5 << <span class="stringliteral">"and should be 5"</span>;
</pre></div><p>...will actually print:</p>
<div class="fragment"><pre class="fragment"> My value is 5 and should be 5
</pre></div><h2><a class="anchor" id="compilecontrol">
Compile-time verbosity control</a></h2>
<p>During the compile time certain defines can be used to turn-off debug messages. Those defines are:</p>
<div class="fragment"><pre class="fragment"> CONTEXT_LOG_HIDE_TEST
CONTEXT_LOG_HIDE_DEBUG
CONTEXT_LOG_HIDE_WARNING
CONTEXT_LOG_HIDE_CRITICAL
</pre></div><p>A given define makes a respective macro message evaluate to an empty code. To be precise: it makes the macro message evaluate to an inline do-nothing class that is optimized by the compiler to do nothing.</p>
<p>When ie. <code>CONTEXT_LOG_HIDE_DEBUG</code> define is used to turn off <code><a class="el" href="logging_8h.html#ad9c4e9fd2b26240900ff7c74cd7e8404">contextDebug()</a></code> messages, the actual string content of the debug messages is <b>not</b> included in the binary and during runtime the machine does not spend time evaluating it.</p>
<p>Those compile-time control defines are integrated in the build/configure system.</p>
<h2><a class="anchor" id="runtimecontrol">
Run-time verbosity control</a></h2>
<p>During run-time, the amount of debugging can be limited (filtered) but it can't be increased (expanded). In other words, if a package was compiled with warnings-only, it's not possible to make it show debug messages at runtime. But it is possible to make it criticals-only.</p>
<p>The filtering happens via env variables. The major player is the <code>CONTEXT_LOG_VERBOSITY</code> variable which can be set to <code>TEST</code>, <code>DEBUG</code>, <code>WARNING</code> and <code>CRITICAL</code>. The <code>CONTEXT_LOG_VERBOSITY</code> specifies the minimal level of the messages shown. Ie. <code>CONTEXT_LOG_VERBOSITY</code> set to <code>WARNING</code> will show only warning and criticals.</p>
<p>The format of the output can be tweaked with <code>CONTEXT_LOG_HIDE_TIMESTAMPS</code> and <code>CONTEXT_LOG_USE_COLOR</code>. The first one makes the messages shorter by skipping the timestamp info. The second one adds a little bit of ANSI coloring to the messages.</p>
<p><code>CONTEXT_LOG_SHOW_MODULE</code> will filter-out (kill) all messages <b>except</b> the ones coming from the specified module. Ie.:</p>
<div class="fragment"><pre class="fragment"> CONTEXT_LOG_SHOW_MODULE=<span class="stringliteral">"subscriber"</span> ./some-binary
</pre></div><p>...will run <code></code>./some-binary showing log messages <b>only</b> from <code>subscriber</code> module.</p>
<p>Lastly, <code>CONTEXT_LOG_HIDE_MODULE</code> will hide log messages coming from the specified module. All other messages will be show.</p>
<h2><a class="anchor" id="modules">
Modules in logging</a></h2>
<p>In previous section we discussed and mentioned modules. For the purpose of logging, a module is a piece of code (not neccesarily limited to one binary or shared object) that forms one component (feature-wise). Specyfying and naming the modules is used to set the origin of the logging messages.</p>
<p>The logging module is set using the <code>CONTEXT_LOG_MODULE_NAME</code> define. It should be (in most cases) defined in the build system and automatically applied to the whole source code. Typically (with autotools) this can be achieved with something similar too:</p>
<div class="fragment"><pre class="fragment"> ...
AM_CXXFLAGS = <span class="stringliteral">'-DCONTEXT_LOG_MODULE_NAME="libtest"'</span>
...
</pre></div><p>If <code>CONTEXT_LOG_MODULE_NAME</code> is undefined, the log messages will be marked as coming from an <b>"Undefined"</b> module.</p>
<h2><a class="anchor" id="features">
Featues</a></h2>
<p>It's possible also to assign logging messages to feature groups and control the output based on that. Features can be compared to tags - one message can belong to zero or more features. To add to a feature to a log message:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="logging_8h.html#ad9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <a class="code" href="logging_8h.html#afbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"threads"</span>) << <span class="stringliteral">"Message goes here"</span> << someVariable;
<a class="code" href="logging_8h.html#ad9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <a class="code" href="logging_8h.html#afbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"threads"</span>) << <a class="code" href="logging_8h.html#afbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"something"</span>) << <span class="stringliteral">"Message..."</span>;
</pre></div><p>It doesn't matter where features are added to the message. There is no specific order required. The following syntax is supported as well:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="logging_8h.html#ad9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <a class="code" href="logging_8h.html#afbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"threads"</span>) << <span class="stringliteral">"Some message..."</span> << <a class="code" href="logging_8h.html#afbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"another"</span>);
</pre></div><p>There are two enviornment variables that control the output of messages vs. features: <b>CONTEXT_LOG_SHOW_FEATURES</b> and <b>CONTEXT_LOG_HIDE_FEATURES</b>. Both take a comma-separated list of features.</p>
<p>If you specify CONTEXT_LOG_SHOW_FEATURES only messages with given features will be printed to the screen. If you specify <b>CONTEXT_LOG_HIDE_FEATURES</b>, messages with the specified features will be hidden (not displayed). For example:</p>
<div class="fragment"><pre class="fragment"> CONTEXT_LOG_SHOW_FEATURES=<span class="stringliteral">"threads,util"</span> ./some-binary
</pre></div><p>...will make <b>only</b> the messages belonging to "threads" or "util" features displayed.</p>
<div class="fragment"><pre class="fragment"> CONTEXT_LOG_HIDE_FEATURES=<span class="stringliteral">"threads,util"</span> ./some-binary
</pre></div><p>...will hide all logging messages belonging to "threads" and "util" feature groups.</p>
<h2><a class="anchor" id="vanilla">
Vanilla</a></h2>
<p>If the default logging output is too much for you, it's possible to set a CONTEXT_LOG_VANILLA enviornment variable. This will simplify the logging output greatly -- no timestamps will be printed, no module information will be printed, no line/function/class info will be printed. </p>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on Mon Oct 19 14:21:01 2009 for libcontextsubscriber by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
|
