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:

Trace enables you to output arbitrary informational messages, including an object's state, to any ostream.
Trace statements automatically output the name of the file containing the executing code, the line number within that file, and the address of the object, if a member function is being traced.
Trace can connect to other products for special-purpose output handling, such as storing output in a database or sending output over a network.

Trace gives you flexibility and control over the type and amount of information produced. Every trace statement has a severity level associated with it. At compile-time you decide the maximum level of tracing to compile into your application. At runtime you can filter the data further with environment variables.
Trace enables you to select at runtime the specific functions that you want tracing output from. You can also select all the functions in a particular class or package, and selectively turn off tracing for functions you're not interested in tracing.
Trace provides a runtime filter that you can compile into your application to dynamically control the level of tracing messages that your application generates.
Trace overhead can be removed entirely by recompiling your application after testing and debugging are complete.

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

Level	Severity	Description
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.