Table of Contents
- General Purpose
- Beginner's manual
- Defining traces
- Deciding what trace to log
- What does the output look
like
- 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,
we
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
without
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
LobTraceStream.
2. Beginner's
manual
Matthew WALKER wrote an
excellent
page to guide you in your very first steps with LTS.
http://www.massey.ac.nz/~mgwalker/misc/lobtracestream/index.html
3. Defining traces
Each trace you will add to your code will have two attributes: a
Module
name and
a
traceLevel.
The traceLevel defines the severity of the trace. LobTraceStream provides
7 levels:
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,
DB access,
Code/Encode, CodeGeneration, MemoryAlloc, Statistics, Utils, Plotting,
Mailing, whatever.
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
others.
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
the traces.
Once the problem is corrected, set the traces back to a less verbose
level.
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
are logged.
INOUT, TRACE and DEBUG are rejected.
5. What does the output
look like
Traces will be logged to files, in Text or XML format. Traces can
also be redirected to the
standard output (cout).
Text format:
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]
XML format:
<LobTrace module="SQL" level="WARNING"
date="12-aug-2002 14:29:35"
line="22" file="./example1.cpp">
<text>Unexpected value : i =
</text><int>
3</int>
</LobTrace
>
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:
lobtracestream.h
and
lobtracestream.cpp
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:
- Add
lobtracestream.cpp
to your makefile
- Add
#include <lobtracestream.h>
in all the .cpp
files that need traces.
- Edit
lobtracestream.h
and lobtracestream.cpp
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():
LOB_TRACE_INIT("myApp_trace.ini",
"myApp_");
- 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;
That's it.
You noticed that only 2 macros were used (
LOB_TRACE_INIT
and
LOB_TRACE
) 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
class
LobTraceStreamQt which makes
the tracing of the most common Qt classes easier.
Example
QTable myTable;
[...]
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.
Module
|
Description
|
Date
|
File
|
Line
|
Level
|
MAILING |
Empty cell in myTable:
QTable size = [2,3] |
Louis |
BAYLE |
lbayle@users.sourceforge.net |
Matthew
|
WALKER
|
|
|
|
16-dec-2002 21:38:23 |
example5Dlg.cpp |
103 |
ERROR |
Supported classes
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
- Add
#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,
like HTML.
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 to convert
XML trace outputs to an HTML file,
but if you use
Mozilla, you can
open the XML files directly,
without any transformation !
Note:
Be sure to put
lobtracestream.dtd
&
lobtrcestream.xsl
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.
Conclusion
LobTraceStream is good for you. ;-)
Louis BAYLE
Last update: 16 Dec. 2002