diff options
Diffstat (limited to 'libcontextsubscriber/doc/html/logging.html')
| -rw-r--r-- | libcontextsubscriber/doc/html/logging.html | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/libcontextsubscriber/doc/html/logging.html b/libcontextsubscriber/doc/html/logging.html new file mode 100644 index 00000000..17879098 --- /dev/null +++ b/libcontextsubscriber/doc/html/logging.html @@ -0,0 +1,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 Nov 9 15:31:10 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> |