diff options
Diffstat (limited to 'libcontextprovider/doc/html/logging.html')
| -rw-r--r-- | libcontextprovider/doc/html/logging.html | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/libcontextprovider/doc/html/logging.html b/libcontextprovider/doc/html/logging.html new file mode 100644 index 00000000..87ce2135 --- /dev/null +++ b/libcontextprovider/doc/html/logging.html @@ -0,0 +1,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 Wed Sep 30 10:23:55 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> |