Event Specification for the Java Profiler

This document describes the trace XML format specification (trace.dtd) which is used by the Java Profiler. The data output of the Java Profiler is a set of XML elements, that can either be emitted as fragments within a non-XML trace stream or as part of a valid XML document.

The following topics are covered:


IDs

This specification refers to some attributes of the elements as various kinds of IDs. Threads, classes, methods, and objects each have unique IDs. 

Each ID has a defining element and an undefining element. A defining element provides the information related to an ID. For example, the defining element for a thread ID contains, among other entries, the name of the thread. 

An ID is valid until its undefining element arrives. An undefining element invalidates the ID, whose value may be reused later as a different kind of ID. The value of a thread ID, for example, may be redefined as a method ID after the thread ends. 

ID Defining element Undefining element
transientThreadId threadStart threadEnd
threadId threadStart threadEnd
transientObjId objAlloc, objMove, objDef objFree, objMove
objId objAlloc objFree
transientClassId classDef, objDef classUnload, objMove
classId classDef, objDef classUnload, objMove
methodId methodDef defining classUnload
nodeId node not applicable
processId processCreate not available
agentId agentCreate agentDestroy*
traceId traceStart traceEnd*
newObjId objMove not applicable

* The ID is only logically undefined since it is UUID (universal unique identifier) which is guaranteed to always be unique.

Assuming the defining elements are enabled, the defining element is guaranteed to be sent before the ID appears in other elements. 

Although the actual XML elements intentionally contain very little document structure, there is a logical hierarchy defined by the relationships of the id/idref attributes. Specifically, a <node nodeId> contains a <processCreate processId, nodeIdRef> contains an <agentCreate agentId, processIdRef> contains a <traceStart traceId, agentIdRef> contains most other elements by means of the traceIdRef, where each element refers back to its parent through their specific idref attribute.  

Common attributes

Many event elements share the same attributes. The following attributes appear on more than one element:

time
The time at which the event started. The format of the time attribute is "utc.fff" where
threadId/threadIdRef
threadId defines and threadIdRef refers to the thread (environment in JVMPI terms) that the element occurred in.  threadId's are unique within the scope of a trace regardless of how many threads are started and ended. Expressed as an unsigned 32-bit value formatted as a string. 
methodId/methodIdRef
methodId defines and methodIdRef refers to the method that the element is associated with. Expressed as a 32-bit unsigned value in string format. 
ticket
Identifies a specific instance of a method invocation (methodEntry and methodExit, or methodCall and methodReturn), using a counter that is unique within the current thread. The ticket may be a list of 32-bit unsigned values (in string format) to allow for more than 32-bit unsigned values. The ticket attribute syntax is:
ticket="number[,number]*" where the numbers are listed from low order to high order.
transientObjId/transientObjIdRef
transientObjId defines and transientObjIdRef refers to the object associated with the event. Expressed as a 32-bit unsigned value in string format. The obj_id associated with a given object may change during garbage collection. This can be tracked by observing objMove elements. Generally, it is safer to use objId and objIdref respectively to refer to objects, unless low-level memory analysis is required.
objId/objIdRef
objId defines and objIdRef refers to the object associated with the event, but unlike transientObjId and transientObjIdRef, cannot be changed by garbage collection. Expressed as a 32-bit unsigned value in string format. 
transientClassId/transientClassIdRef
transientClassId defines and transientClassIdRef refers to the class associated with the event. Expressed as a 32-bit unsigned value in string format. The classId associated with a given class may change during garbage collection. This can be tracked by observing objMove elements. Generally, it is safer to use classId and classIdref respectively to refer to classes, unless low-level memory analysis is required.
classId/classIdref
classId defines and classIdRef refers to the class associated with the event, but unlike transientClassId and transientClassIdRef, cannot be changed by garbage collection. Expressed as a 32-bit unsigned value in string format. 
threadCpuTime
The total CPU time consumed by the current thread in nanoseconds at the time of the event. The format of the thread_cpu_time attribute is "sss.fff" where
sequenceCounter
A counter indicating the sequence of the current event relative to other events associated with the current object. The count is 0 at object allocation and is incremented by one for each:

The sequenceCounter will remain "0" if invoking a static method.

collationValue
The purpose of this attribute is to allow elements to be collated when emitted on a stream that does not guarantee the order of delivery. It starts from the value "1" on a traceStart element, and is incremented for each element emitted after that. The collation_value is scoped by the traceStart and traceEnd elements. The collation_value may be a list of 32-bit unsigned values (in string format) to allow for more than 32-bit unsigned values. The collation_value attribute syntax is:
collationValue="number[,number]*" where the numbers are listed from low order to high order.
traceId/traceIdRef
traceId defines and traceIdRef refers to a UUID that uniquely identifies the trace instance.
isArray
Defines the data type of an array. Values can be:

VALUE

MEANING

"0" normal object (i.e., not an array)
"2" array of objects
"4" array of booleans
"5" array of chars
"6" array of floats
"7" array of doubles
"8" array of bytes
"9" array of shorts
"10" array of ints
"11" array of longs
 

Structural elements

When emitted as part of a valid XML document, the trace information is contained under a root TRACE element.

<TRACE>
  <node/>
  <processCreate/>
  <agentCreate/>
      ...
  all other events
      ...
  <agentDestroy/>
</TRACE>

The information conforms to the associated DTD (trace.dtd) and schema (trace.xsd), which declare these elements.

Trace behavior elements

The following elements provide information about the trace as a whole:

Thread elements

The following elements provide information about threads. Other elements will point to a THREAD element's thread_id to identify the thread they are running in.

Class elements

Although technically part of the classDef event, the method element is broken out into a separate element so that it can be optionally output only when referenced.

Object elements

The element objAlloc traces storage allocation. It has its own section because it also holds identity information for an object, which can be referred to by method events associated with the object, such as a methodEntry event.

Method elements

The following elements provide information about methods:

methodEntry and methodExit are output when a method is entered, and when the method returns respectively. methodCall and methodReturn are output when a method is about to be called, and after a method returns.  

The InvocationContext element holds identity information so that a methodEntry can determine who invoked the method irregardless of loaction. InvocationContext information will identify either a methodCall or methodEntry of a remote agent for distributed invocations.

The objDef element holds identity information for an object, which can be referred to by elements associated with the object, such as the value element.

The value element is used to reference a data value, either for parameter values in a methodCall, or for the return value of a methodReturn.

methodCount tracks the number of times a particular method has been invoked. This element is designed to aid in collecting code coverage information. A methodCount element is produced for every method for every class loaded by the application. The count includes all method invocations regardless of whether tracing was enabled or not. In other words, the data is collected even before a traceStart and even after a traceEnd. The elements are produced just prior to the agentDestroy element being produced. In addition, an agent may be requested to produce the methodCount elements at any arbitrary time before the agentDestroy element is produced.

Lines

The line element is produced for each line that is executed.

Memory Management elements

The following elements are for tracing storage management:

Exception elements

The throw and catch elements encapsulate the exception behavior of the application. 

JVM elements

These elements track the initialization and shutdown of the Java Virtual Machine (JVM):

Monitor elements

These elements track synchronization events.