Using Trace

SourcePro Core : Threads Module User's Guide : PART III Foundation Packages : The Execution Tracing Package : Using Trace

Using Trace

These are the basic steps required to generate trace output:

1. Put set declaration macros in your code to make the functions traceable. (See Using Set Declaration Macros.)

2. Put trace event macros in your code to generate trace output. (See Using Event Generation Macros.)

3. Create at least one trace event client to process the trace output. (See Using Trace Clients.)

4. Choose a combination of compile time and runtime options for controlling the severity levels of the events reported. (See Controlling Trace Output.)

5. Define environment variables to turn sets on or off at runtime. (See Setting Environment Variables for Event Sets.)

Example 49 illustrates the steps required to generate trace output in a global function. The following code is taken from buildspace\examples\trace\helloTrace.cpp.

Example 49 – Generating trace output

#define RW_USER_TRACE_LEVEL 8 //1

#include <rw/trace/trace.h> //2

// Create a trace client that logs messages to cerr

RWTraceOstreamClient myTraceClient(cerr); //3

int main()

{

// Declare the function as traceable and use

// the environment variable named "main” to control

// trace event generation from this function

RW_USER_TRACEABLE_FUNCTION("main”); //4

// Connect the client to the singleton manager

myTraceClient.connectToManager(); //5

// Generate some trace events

RW_USER_TRACE_DEBUG("This is a debug message”); //6

RW_USER_TRACE_INFO("This is an informational message”); //7

return 0;

}

//1 Sets the trace level to maximum (8). This ensures that all trace events are compiled into the executable. If you define the trace level in the program, as shown here, this macro must be set before including trace.h. This macro could also be set on the command line when the program is compiled, using the -DRW_USER_TRACE_LEVEL=8 flag.

//2 Includes the trace umbrella header.

//3 Creates a client that logs messages to cerr. The function is declared global, so that all events from main() are processed before the client’s destruction.

//4 This is a set declaration macro. It declares the function as traceable and assigns it the name main, which is used as the environment variable name to toggle the generation of trace events in this function. This macro also generates the function ENTRY and EXIT events.

//5 Connects the client to the trace manager.

//6 This is an event generation macro. It generates a DEBUG trace event.

//7 This is also an event generation macro. It generates an INFO trace event.

To see output, set the main or rw_user environment variable to ON. rw_user works because the main() function is declared on line //3 to be a member of the predefined rw_user package set. The program produces this output:

ENTRY|helloTrace.cpp:10|main> Entry

DEBUG|helloTrace.cpp:19|main> This is a debug message

INFO|helloTrace.cpp:20|main> This is an informational message

EXIT|helloTrace.cpp:25|main> Exit