ej.trace

Class Tracer

java.lang.Object

ej.trace.Tracer

public class Tracer
extends java.lang.Object

A Tracer object is used to trace events for debug or monitoring. Tracer are named and can produce a limited number of different event types.

The following example uses a Tracer object to trace the execution of a method:

 static final int EVT_FOO = 0;

 Trace myTracer = new Tracer("MyTracer", 1);

 int foo(int x, int y) {
        myTracer.recordEvent(EVT_FOO, x, y);
        ...
        myTracer.recordEventEnd(EVT_FOO, z);
        return z;
 }
 

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TRACE_ENABLED_CONSTANT_PROPERTY The value of this boolean constant property is true when the traces are enabled in the system and false otherwise (see Constants).

Constructor Summary

Constructors

Constructor and Description
Tracer(java.lang.String name, int nbEventTypes) Creates a new tracer with the given name.

Method Summary

Modifier and Type	Method and Description
int	getGroupID() Gets the group identifier.
static boolean	isTraceStarted() Tests whether the trace system is started or not.
void	recordEvent(int eventId) Record an event for this Tracer.
void	recordEvent(int eventId, int value1) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8, int value9) Record an event for this Tracer.
void	recordEvent(int eventId, int value1, int value2, int value3, int value4, int value5, int value6, int value7, int value8, int value9, int value10) Record an event for this Tracer.
void	recordEventEnd(int eventId) Record the end of the execution of an event for this Tracer.
void	recordEventEnd(int eventId, int value1) Record the end of the execution of an event for this Tracer.
static void	startTrace() Starts to record the events.
static void	stopTrace() Stops to record the events.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TRACE_ENABLED_CONSTANT_PROPERTY

public static final java.lang.String TRACE_ENABLED_CONSTANT_PROPERTY

The value of this boolean constant property is true when the traces are enabled in the system and false otherwise (see Constants).

It can be used to prevent unnecessary code to be embedded and executed when the traces are disabled:

 if (Constants.getBoolean(Tracer.TRACE_ENABLED_CONSTANT_PROPERTY)) {
        int myEventValue = getMyEventValue();
        mytracer.recordEvent(myEvent, myEventValue);
 }
 

See Also:

Constant Field Values

Constructor Detail

Tracer

public Tracer(java.lang.String name,
              int nbEventTypes)
       throws java.lang.InternalError

Creates a new tracer with the given name. The created Tracer defines nbEventTypes types of events. The event IDs available for this group are from 0 to nbEventTypes-1.

Parameters:

name - name that identifies the group. Must not be null.

nbEventTypes - maximum number of event types available for the group.

Throws:

java.lang.InternalError - if the tracer cannot be created.

Method Detail

startTrace

public static void startTrace()

Starts to record the events.

By default, the trace system is stopped.

stopTrace

public static void stopTrace()

Stops to record the events. When the record system is stopped, any call to the recordEvent(int) methods will not record any events.

By default, the trace system is stopped.

isTraceStarted

public static boolean isTraceStarted()

Tests whether the trace system is started or not.

Returns:

true if the trace system is started, false otherwise.

getGroupID

public int getGroupID()

Gets the group identifier. This identifier is unique for each Tracer instance.

Returns:

the group unique identifier.

recordEvent

public void recordEvent(int eventId)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

recordEvent

public void recordEvent(int eventId,
                        int value1)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4,
                        int value5)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

value5 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4,
                        int value5,
                        int value6)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

value5 - custom value for the event.

value6 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4,
                        int value5,
                        int value6,
                        int value7)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

value5 - custom value for the event.

value6 - custom value for the event.

value7 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4,
                        int value5,
                        int value6,
                        int value7,
                        int value8)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

value5 - custom value for the event.

value6 - custom value for the event.

value7 - custom value for the event.

value8 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4,
                        int value5,
                        int value6,
                        int value7,
                        int value8,
                        int value9)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

value5 - custom value for the event.

value6 - custom value for the event.

value7 - custom value for the event.

value8 - custom value for the event.

value9 - custom value for the event.

recordEvent

public void recordEvent(int eventId,
                        int value1,
                        int value2,
                        int value3,
                        int value4,
                        int value5,
                        int value6,
                        int value7,
                        int value8,
                        int value9,
                        int value10)

Record an event for this Tracer. The given event ID must be valid for this Tracer (i.e. between 0 and nbEventTypes-1 included where nbEventTypes is the value given to the Tracer(String, int) constructor).

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event.

value2 - custom value for the event.

value3 - custom value for the event.

value4 - custom value for the event.

value5 - custom value for the event.

value6 - custom value for the event.

value7 - custom value for the event.

value8 - custom value for the event.

value9 - custom value for the event.

value10 - custom value for the event.

recordEventEnd

public void recordEventEnd(int eventId)

Record the end of the execution of an event for this Tracer. Call this method to trace the duration of an event previously record with one of the recordEvent(int) methods. This method should not be called for event that has no duration.

For example, if you want to trace the execution of a method, you can call recordEvent(int) at the beginning of the function and recordEventEnd(int) at the end of the function.

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

recordEventEnd

public void recordEventEnd(int eventId,
                           int value1)

Record the end of the execution of an event for this Tracer. Call this method to trace the duration of an event previously record with one of the recordEvent(int) methods. This method should not be called for event that has no duration.

For example, if you want to trace the execution of a method, you can call recordEvent(int) at the beginning of the function and recordEventEnd(int, int) at the end of the function.

The record is done only if the trace system is started (see startTrace()).

Parameters:

eventId - ID of the event.

value1 - custom value for the event end.