A C++ Trace Mechanism

Table of Contents

1. General Purpose
2. Beginner's manual
   
3. Defining traces
4. Deciding what trace to log
5. What does the output look like
6. Including LobTraceStream to your code
   
7. Tracing Trolltech Qt objects
8. 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:

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:

1. Add lobtracestream.cpp to your makefile
2. Add #include <lobtracestream.h> in all the .cpp files that need traces.
3. Edit lobtracestream.h and lobtracestream.cpp to add your own modules
   (search for 'CUSTO' to know where and what to edit).
4. Initialize the LobTrace mechanism by adding the following line at the beginning of your main():
   LOB_TRACE_INIT("myApp_trace.ini", "myApp_");
5. Create a 'myApp_trace.ini' file in which you define the traceLevels for your modules.
6. 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

1. Add #include <lobtracestreamqt.h> in all the .cpp files that need traces
   ( instead of #include <lobtracestream.h> )
2. Add the following line to your qt project file (*.pro) :
   DEFINES    += LOBTRACE_QT
3. 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