Table of Contents
- General Purpose
- Beginner's manual
- Defining traces
- Deciding what trace to log
- What does the output look
- Including LobTraceStream
to your code
- Tracing Trolltech Qt objects
- Using XSLT to view trace
outputs in your web browser
1. General Purpose
LobTraceStream (LTS) logs the trace messages of your application.
Most of the time, we (developpers) need as many traces as possible while
coding & debugging an application. But once we get a stable release,
would like to have fewer but more relevant trace outputs. And if a problem
rises, we would like to have detailed traces concerning that problem
being spammed by all the other traces the application can generate.
Another point is that we do not want to spend too much time implementing
traces, as it is not the main purpose of the application.
Tracing needs to be simple, doesn't it ?!
If this is what you expect from a trace mechanism, then give a try to
Matthew WALKER wrote an excellent
to guide you in your very first steps with LTS.
3. Defining traces
Each trace you will add to your code will have two attributes: a Module
The traceLevel defines the severity of the trace. LobTraceStream provides
INOUT, DEBUG, TRACE, WARNING, ERROR, CRITICAL, EXCEPTION.
The modules are specific to your application. While the design phase
of your project,
you certainly defined some groups of functionalities like: Communication,
Code/Encode, CodeGeneration, MemoryAlloc, Statistics, Utils, Plotting,
Here, a typical example of a simple trace implementation:
LOB_TRACE(UTILS, DEBUG) << "Hello world, i = " << i << lt_endl;
4. Deciding what trace to log
By assigning a traceLevel and a module name to each trace, you will be
able to classify
traces with a pretty good precision. All we need to do now, is to tell
the application which
traces are to be logged and which ones are to be rejected.
This is done in a configuration file
that will be parsed at the
starting of the application.
In this file, you will define per module, the traceLevels that you
consider as relevant
Thus, if you have a problem in a part of your application, you will be
able to set a
maximum of traces on the concerned module and get less traces for the
If the app has shipped and the customer reports a bug, just ask him
to modify the
traceLevel of the concerned module, restart the application, and send
Once the problem is corrected, set the traces back to a less verbose
config file example:
GENERAL = "WARNING"
UTILS = "DEBUG"
DEMOMODULE = "TRACE"
If tracelevel is set to WARNING,
then all traces arriving with level WARNING, ERROR, CRITICAL and EXCEPTION
INOUT, TRACE and DEBUG are rejected.
5. What does the output
Traces will be logged to files, in Text or XML format. Traces can
also be redirected to the
standard output (cout).
12-aug-2002 14:26:26 DEBUG UTILS: "Hello world,
i = 73" [./foobar.cpp:52]
12-aug-2002 14:26:28 TRACE GENERAL: "This is an integer
: 123" [./example1.cpp:56]
<LobTrace module="SQL" level="WARNING"
<text>Unexpected value : i =
XML output will allow you to see colored traces in your web browser.
( See the XSLT section
of this page for more information )
6. Including LobTraceStream
to your code
LobTraceStream is a set of 3 classes, defined in two files:
But you do not need to care about those classes and their instanciation;
you just have to use the defined macros.
There are two sets of macros:
- the 5 basic macros
(for a single threaded application).
- the 5 multi-thread/multi-trace macros
Using the basic macros:
lobtracestream.cpp to your makefile
#include <lobtracestream.h> in all the .cpp
files that need traces.
to add your own modules
(search for 'CUSTO' to know where and what to edit).
- Initialize the LobTrace mechanism by adding the following line
at the beginning of your main():
- Create a 'myApp_trace.ini' file in which you define the traceLevels
for your modules.
- Use the trace macro each time you want to trace something:
LOB_TRACE(GENERAL, TRACE) <<
"This is an integer : " << 123 << lt_endl;
You noticed that only 2 macros were used (
) the 3 others will
allow to trace Exceptions and the entrance and exit of functions.
This will provide with the function calling stack if you set
the module traceLevel to INOUT.
7. Tracing Trolltech-Qt objects
If you are building an application that uses the Qt library
, LTS provides an additional
the tracing of the most common Qt classes easier.
LOB_TRACE(MAILING, ERROR) << "Empty cell in myTable: " << myTable << lt_endl;
will trace the content of each cell of myTable. If you generate XML trace
outputs and use XSL to view traces,
then myTable will be represented as an easy-to-read HTML Table.
||Empty cell in myTable:
|QTable size = [2,3]
| 16-dec-2002 21:38:23
QString, QStringList, QLineEdit, QTextEdit, QTable, QCheckBox, QRadioButton
You can easily add support for other classes.
Do not hesitate to contribute to the LobTraceStream project.
Including LobTraceStreamQt to your code
#include <lobtracestreamqt.h> in all the .cpp
files that need traces
( instead of
#include <lobtracestream.h> )
- Add the following line to your qt project file (*.pro) :
DEFINES += LOBTRACE_QT
- Use the LOB_TRACE macro as before.
8. Using XSLT to view
trace outputs in your web browser
XSL Transformations allow to convert an XML file in any other text format,
Formating traces in HTML allows to set colors for the different trace levels,
and adapt the format to the displayed objects (tables, lists, booleans, ...
You can use Xalan
XML trace outputs to an HTML file,
but if you use Mozilla
, you can
open the XML files directly,
without any transformation !
Be sure to put
in the same
directory than your xml trace files.
Take a look at the screenshots
for a quick
overview of the output.
Follow this link
to see an example of a trace
file converted to HTML with XSLT.
LobTraceStream is good for you. ;-)
Last update: 16 Dec. 2002