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:
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.
Many event elements share the same attributes. The following attributes appear on more than one element:
The sequenceCounter will remain "0" if invoking a static method.
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 |
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.
The following elements provide information about the trace as a whole:
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.
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.
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.
The following elements provide information about methods:
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.
The line element is produced for each line that is executed.
The following elements are for tracing storage management:
The throw and catch elements encapsulate the exception behavior of the application.
These elements track the initialization and shutdown of the Java Virtual Machine (JVM):
These elements track synchronization events.