org.opensolaris.os.dtrace
Class ProbeData

java.lang.Object
  extended by org.opensolaris.os.dtrace.ProbeData
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<ProbeData>

public final class ProbeData
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<ProbeData>

Data generated when a DTrace probe fires, contains one record for every record-generating action in the probe. (Some D actions, such as clear(), do not generate a ProbeData record.) A Consumer gets data from DTrace by registering a listener to get probe data whenever a probe fires:


     Consumer consumer = new LocalConsumer();
     consumer.addConsumerListener(new ConsumerAdapter() {
         public void dataReceived(DataEvent e) {
             ProbeData probeData = e.getProbeData();
             System.out.println(probeData);
         }
     });
 
Getting DTrace to generate that probe data involves compiling, enabling, and running a D program:

     try {
         consumer.open();
         consumer.compile(program);
         consumer.enable(); // instruments code at matching probe points
         consumer.go(); // non-blocking; generates probe data in background
     } catch (DTraceException e) {
         e.printStackTrace();
     }
 
Currently the ProbeData instance does not record a timestamp. If you need a timestamp, trace the built-in timestamp variable in your D program. (See the Built-in Variables section of the Variables chapter of the Solaris Dynamic Tracing Guide).

Immutable. Supports persistence using XMLEncoder.

See Also:
Consumer.addConsumerListener(ConsumerListener l), ConsumerListener.dataReceived(DataEvent e), Serialized Form

Nested Class Summary
static class ProbeData.KeyField
          Enumerates the fields by which ProbeData may be sorted using the getComparator() convenience method.
 
Constructor Summary
ProbeData(int enabledProbeID, int cpuID, ProbeDescription p, Flow f, java.util.List<Record> recordList)
          Creates a probe data instance with the given properties and list of records.
 
Method Summary
 int compareTo(ProbeData d)
          Natural ordering of probe data.
static java.util.Comparator<ProbeData> getComparator(ProbeData.KeyField... f)
          Convenience method, gets a comparator that sorts multiple ProbeDescription instances by the specified field or fields.
 int getCPU()
          Gets the ID of the CPU on which the probe fired.
 ProbeDescription getEnabledProbeDescription()
          Gets the enabled probe description.
 int getEnabledProbeID()
          Gets the enabled probe ID.
 Flow getFlow()
          Gets the current state of control flow (function entry or return, and depth in call stack) at the time of the probe firing that generated this ProbeData instance, or null if such information was not requested with the flowindent option.
 java.util.List<Record> getRecords()
          Gets the records generated by the actions of the probe that fired, in the same order as the actions that generated the records.
 java.lang.String toString()
          Gets a string representation of this ProbeData instance useful for logging and not intended for display.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ProbeData

public ProbeData(int enabledProbeID,
                 int cpuID,
                 ProbeDescription p,
                 Flow f,
                 java.util.List<Record> recordList)
Creates a probe data instance with the given properties and list of records. Supports XML persistence.

Parameters:
enabledProbeID - identifies the enabled probe that fired; the ID is generated by the native DTrace library to distinguish all probes enabled by the source consumer (as opposed to all probes on the system)
cpuID - non-negative ID, identifies the CPU on which the probe fired
p - identifies the enabled probe that fired
f - current state of control flow (entry or return and depth in call stack) at time of probe firing, included if flowindent option used, null otherwise
recordList - list of records generated by D actions in the probe that fired, one record per action, may be empty
Throws:
java.lang.NullPointerException - if the given probe description or list of records is null
Method Detail

getComparator

public static java.util.Comparator<ProbeData> getComparator(ProbeData.KeyField... f)
Convenience method, gets a comparator that sorts multiple ProbeDescription instances by the specified field or fields. If more than one sort field is specified, the probe data are sorted by the first field, and in case of a tie, by the second field, and so on, in the order that the fields are specified.

Parameters:
f - field specifiers given in descending order of sort priority; lower priority fields are only compared (as a tie breaker) when all higher priority fields are equal
Returns:
non-null probe data comparator that sorts by the specified sort fields in the given order

getEnabledProbeID

public int getEnabledProbeID()
Gets the enabled probe ID. Identifies the enabled probe that fired and generated this ProbeData. The "epid" is different from ProbeDescription.getID() in that it identifies a probe among all probes enabled by the source Consumer, rather than among all the probes on the system.

Returns:
the enabled probe ID generated by the native DTrace library

getCPU

public int getCPU()
Gets the ID of the CPU on which the probe fired.

Returns:
ID of the CPU on which the probe fired

getEnabledProbeDescription

public ProbeDescription getEnabledProbeDescription()
Gets the enabled probe description. Identifies the enabled probe that fired and generated this ProbeData.

Returns:
non-null probe description

getFlow

public Flow getFlow()
Gets the current state of control flow (function entry or return, and depth in call stack) at the time of the probe firing that generated this ProbeData instance, or null if such information was not requested with the flowindent option.

Returns:
a description of control flow across function boundaries, or null if Consumer.getOption(Option.flowindent) returns Option.UNSET
See Also:
Consumer.setOption(String option), Option.flowindent

getRecords

public java.util.List<Record> getRecords()
Gets the records generated by the actions of the probe that fired, in the same order as the actions that generated the records. The returned list includes one record for every record-generating D action (some D actions, such as clear(), do not generate records).

Returns:
non-null, unmodifiable list view of the records belonging to this ProbeData in the order of the actions in the DTrace probe that generated them (record-producing actions are generally those that produce output, such as printf(), but also the exit() action)

compareTo

public int compareTo(ProbeData d)
Natural ordering of probe data. Sorts probe data by records first, then if record data is equal, by enabled probe ID.

Specified by:
compareTo in interface java.lang.Comparable<ProbeData>
Parameters:
d - probe data to be compared with this probe data
Returns:
a negative number, zero, or a positive number as this probe data is less than, equal to, or greater than the given probe data
Throws:
java.lang.NullPointerException - if the given probe data is null
java.lang.ClassCastException - if record lists of both ProbeData instances are not mutually comparable because corresponding list elements are not comparable or the lists themselves are different lengths
See Also:
getComparator(KeyField[] f)

toString

public java.lang.String toString()
Gets a string representation of this ProbeData instance useful for logging and not intended for display. The exact details of the representation are unspecified and subject to change, but the following format may be regarded as typical:

 class-name[property1 = value1, property2 = value2]
 

Overrides:
toString in class java.lang.Object