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 HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>libcontextprovider: </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.5.8 -->
<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">
The library (and ContexKit in general) use a simple logging system designed to unify the output and make the debugging easier.<h2><a class="anchor" name="API">
API</a></h2>
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>
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>
The log messages can be used like this:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="logging_8h.html#bfb57c8a40821bf0caa9a29a8dfc47b7">contextTest</a>() << <span class="stringliteral">"This is some message"</span>;
<a class="code" href="logging_8h.html#d9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <span class="stringliteral">"My value is:"</span> << someVariable;
<a class="code" href="logging_8h.html#63433fe15ab356004ccdd4263b0910c0">contextWarning</a>() << <span class="stringliteral">"Expecting key:"</span> << something.getKey();
<a class="code" href="logging_8h.html#7f115b5076497bd3af236e8778940ea1">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#d9c4e9fd2b26240900ff7c74cd7e8404">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" name="compilecontrol">
Compile-time verbosity control</a></h2>
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>
When ie. <code>CONTEXT_LOG_HIDE_DEBUG</code> define is used to turn off <code><a class="el" href="logging_8h.html#d9c4e9fd2b26240900ff7c74cd7e8404">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>
Those compile-time control defines are integrated in the build/configure system.<h2><a class="anchor" name="runtimecontrol">
Run-time verbosity control</a></h2>
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>
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>
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>
<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>
Lastly, <code>CONTEXT_LOG_HIDE_MODULE</code> will hide log messages coming from the specified module. All other messages will be show.<h2><a class="anchor" name="modules">
Modules in logging</a></h2>
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>
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.<h2><a class="anchor" name="features">
Featues</a></h2>
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#d9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <a class="code" href="logging_8h.html#fbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"threads"</span>) << <span class="stringliteral">"Message goes here"</span> << someVariable;
<a class="code" href="logging_8h.html#d9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <a class="code" href="logging_8h.html#fbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"threads"</span>) << <a class="code" href="logging_8h.html#fbeb0b1d3a7070b195c5a6a5a062dc56">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#d9c4e9fd2b26240900ff7c74cd7e8404">contextDebug</a>() << <a class="code" href="logging_8h.html#fbeb0b1d3a7070b195c5a6a5a062dc56">contextFeature</a>(<span class="stringliteral">"threads"</span>) << <span class="stringliteral">"Some message..."</span> << <a class="code" href="logging_8h.html#fbeb0b1d3a7070b195c5a6a5a062dc56">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>
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.<h2><a class="anchor" name="vanilla">
Vanilla</a></h2>
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. </div>
<hr size="1"><address style="text-align: right;"><small>Generated on Fri Oct 23 08:58:39 2009 for libcontextprovider by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
</body>
</html>
|
