Rogue Wave banner
Previous fileTop of DocumentContentsIndexNext file

6.1 Introducing the Execution Tracing Package

Software developers know that writing code is relatively easy. Getting it to run properly and perform as expected is the hard part. Testing and debugging are a significant part of the total development time of any project, and much of that time is spent inserting and removing temporary output statements. Before the software is released, these statements are removed, commented out, or conditionally compiled out, so they do not degrade the performance of the executable. These approaches to debugging, although widely used, are extremely inefficient. Whenever the temporary tracing statements are toggled on or off, the application must be recompiled and re-linked. This problem becomes more serious as the application increases in size.

The Threads.h++ Execution Tracing package generates a record of program execution. With the simple event logging interface, you can trace your applications in a way that is similar to the standard approaches, but more efficient and cost effective.

The Execution Tracing package (Trace) provides the following features:

6.1.1 Interpackage Dependencies

You can use the Execution Tracing package independently. It does not require any other packages in Threads.h++.

6.1.2 Including the Trace Header Files

The rw\trace directory contains a header file for each class, named classname.h. You can also access the declarations for the entire Execution Tracing package through trace.h, an umbrella file that includes the header files for all the classes.

6.1.3 Trace Severity Levels

The Execution Tracing package supports seven severity levels. Table 6 gives some general guidelines for their use.

Table 6 -- Trace severity levels

 
LevelSeverityDescription
2
Fatal
For unrecoverable errors that result in terminating the program. For example, report a fatal trace event before a call to assert(), exit(), or abort().
3
Error
For recoverable errors, such as exceptions that are caught and handled, dropped connections that can be reestablished, and recoverable database errors. Report an error trace event before throwing an exception. Do not generate an error trace event for error conditions reported (by your code) as function return values or for exceptions reporting expected conditions, such as end-of-file, time-out, and illegal-usage.
4
Warning
For advance notice of impending problems. Report a warning trace event, for example, when the program is nearing resource or performance limits.
5
Informational
For documenting program flow. For example, Connected to Client and Startup Complete are representative informational statements.
6
Test
For testing information, such as the state of objects, needed to document that your software performed successfully.
7
Debug
For low-level information used in code debugging or unit testing, such as local variables, loop variables, and branching logic. If error conditions are detected only under debug builds, report them as debug trace events, not as fatal or error events.
8
Entry
For documenting the call order of functions. When a function is called, the statement generates the output message Entry. When the function returns, an Exit message is generated. These messages are generated automatically when a function is declared to be traceable.

Levels 0 and 1 are reserved for internal use.

The Execution Tracing package provides three ways to control trace output based on these severity levels. The RW_USER_TRACE_LEVEL macro sets the level at compile time, the RW_TRACE_LEVEL environment variable further refines the output at program start-up, and the RWTraceLevelFilter class provides runtime control.


Previous fileTop of DocumentContentsIndexNext file

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.