Determining the tracepoint ID of a tracepoint

Throughout the code that makes up the JVM, there are numerous tracepoints. Each tracepoint maps to a unique ID consisting of the name of the component containing the tracepoint, followed by a period (.) and then the numeric identifier of the tracepoint.

These tracepoints are also recorded in two .dat files (TraceFormat.dat and J9TraceFormat.dat) that are shipped with the Java™ runtime environment, and the trace formatter uses these files to convert compressed trace points into readable form.

JVM developers and Service can use the .dat files to enable formulation of trace point ids and ranges for use under -Xtrace when tracking down problems. The next sample is taken from the beginning of J9TraceFormat.dat, which illustrates how this mechanism works:

5.1
j9bcu.0 0 1 1 N Trc_BCU_VMInitStages_Event1 "  Trace engine initialized for module j9dyn"
j9bcu.1 2 1 1 N Trc_BCU_internalDefineClass_Entry " >internalDefineClass %p"
j9bcu.2 4 1 1 N Trc_BCU_internalDefineClass_Exit " <internalDefineClass %p ->"
j9bcu.3 2 1 1 N Trc_BCU_createRomClassEndian_Entry " >createRomClassEndian searchFilename=%s"

The first line of the .dat file is an internal version number. Following the version number is a line for each tracepoint. Trace point j9bcu.0 maps to Trc_BCU_VMInitStages_Event1 for example and j9bcu.2 maps to Trc_BCU_internalDefineClass_Exit.

The format of each tracepoint entry is:
<component.id> <t> <o> <l> <e> <symbol> <template>
where:
<component.id>
is the SDK component name.
<t>
is the tracepoint type (0 through 12), where these types are used:
  • 0 = event
  • 1 = exception
  • 2 = function entry
  • 4 = function exit
  • 5 = function exit with exception
  • 8 = internal
  • 12 = assert
<o>
is the overhead (0 through 10), which determines whether the tracepoint is compiled into the runtime JVM code.
<l>
is the level of the tracepoint (0 through 9). High frequency tracepoints, known as hot tracepoints, are assigned higher level numbers.
<e>
is an internal flag (Y/N) and no longer used.
<symbol>
is the internal symbolic name of the tracepoint.
<template>
is a template in double quotation marks that is used to format the entry.
For example, if you discover that a problem occurred somewhere close to the issue of Trc_BCU_VMInitStages_Event, you can rerun the application with -Xtrace:print=tpnid{j9bcu.0}. That command will result in an output such as: 
14:10:42.717*0x41508a00   j9bcu.0        - Trace engine initialized for module j9dyn
The example given is fairly trivial. However, the use of tpnid ranges and the formatted parameters contained in most trace entries provides a very powerful problem debugging mechanism.

The .dat files contain a list of all the tracepoints ordered by component, then sequentially numbered from 0. The full tracepoint ID is included in all formatted output of a tracepoint; For example, tracing to the console or formatted binary trace.

The format of trace entries and the contents of the .dat files are subject to change without notice. However, the version number should guarantee a particular format.