JProfiler API documentation

com.jprofiler.api.agent.probe
Class ProbeMetaData

java.lang.Object
  com.jprofiler.api.agent.probe.ProbeMetaData

public abstract class ProbeMetaData
extends java.lang.Object

The meta data defines the capabilities of a probe. At startup, each probe is queried once for its meta data via a call to Probe.getMetaData(). In that method, you create an instance with create(String) and call its methods to configure the probe. The meta data provides a fluent interface, so you can append method calls like in ProbeMetaData.create("Test").events(true).recordOnStartup(false).

The help topic on custom probes in the bundled documentation explains how to develop custom probes.

ProbeMetaData

public ProbeMetaData()

create

public static ProbeMetaData create(java.lang.String name)

Creates an meta-data instance. For custom probes defined the JProfiler GUI, you should not call this method, since a meta data instance is already passed to the meta-data script. In that case, the name and description of the probe are already set.

Parameters:

name - the name of the probe. This name is displayed in the JProfiler GUI.

Returns:

the meta-data instance

description

public abstract ProbeMetaData description(java.lang.String description)

Sets the description of the probe. The description is displayed in the probes view and the custom probe configuration or the session settings. If this method is not called, a default description will be displayed.

Parameters:

description - the description

Returns:

this instance

payload

public abstract ProbeMetaData payload(boolean payload)

Configures if the probe collects payload information. The default value is false. If set to true, the hot spots view will be shown. The InterceptorContext.createPayloadInfo(String) and InterceptorContext.createPayloadInfo(String, Object) and published via InterceptorContext.addPayloadInfo(PayloadInfo) for standalone payloads or via create methods in the InterceptorContext that take a PayloadInfo argument.

This only makes sense for interceptor probes.

Parameters:

payload - the value

Returns:

this instance

events

public abstract ProbeMetaData events(boolean events)

Configures if probe retain single events. The default value is false. If set to true, the events view will be shown. If the event count exceeds 100000, events will be consolidated. Events are created with the create methods in ProbeContext and InterceptorContext and are published with ProbeContext.addEvent(ProbeEvent).

Parameters:

events - the value

Returns:

this instance

telemetry

public abstract ProbeMetaData telemetry(boolean telemetry)

Configures if the probe collects telemetry data. The default value is false. If set to true, the telemetries view will be shown. Telemetries must then be configured with calls to addCustomTelemetry(String, Unit, float) and addOpenControlObjectTelemetry(String). Telemetry data is sampled every second with calls to TelemetryProbe.fillTelemetryData(ProbeContext, int[]).

This only makes sense for telemetry probes.

Parameters:

telemetry - the value

Returns:

this instance

controlObjectView

public abstract ProbeMetaData controlObjectView(boolean controlObjectView)

Configures if the probe publishes control objects. The default value is false. If set to true, the control objects view will be shown. Control objects are created with calls to ProbeContext.createOpenEvent(String, Object) or InterceptorContext.createOpenEvent(PayloadInfo, Object).

Parameters:

controlObjectView - the value

Returns:

this instance

recordOnStartup

public abstract ProbeMetaData recordOnStartup(boolean startRecording)

Configures if the probe should record data on startup. The default value is true. In any case, the user can start and stop recording the JProfiler GUI.

Parameters:

startRecording - the value

Returns:

this instance

annotatePayloads

public abstract ProbeMetaData annotatePayloads(boolean annotatePayloads)

Configures if the probe should annotate data into the call tree view. The default value is false. If set to true, you should also call the payloadName(String) method, so you can distinguish payload from different probes in the call tree.

Parameters:

annotatePayloads - the value

Returns:

this instance

payloadName

public abstract ProbeMetaData payloadName(java.lang.String payloadName)

Sets the name of the payload. Then the probe annotates data in the the call tree, the container node for the payload of this probe shows this name.

This only has an effect if annotatePayloads(boolean) is called with the argument true.

Parameters:

payloadName - the name

Returns:

this instance

startTelemetryGroup

public abstract ProbeMetaData startTelemetryGroup(java.lang.String name)

Starts a group of telemetries that can be displayed in the same graph. The telemetries have to have the same units and their values should be in the sme order of magnitude. All subsequent calls to addCustomTelemetry(String, Unit, float) will be added to this group. To start a new group, you have to call this method again. If you never call this method, all telemetries will be in separate graphs.

This only makes sense if the telemetry(boolean) method has been called with the argument true.

Parameters:

name - the name of the telemetry group

Returns:

this instance

addOpenControlObjectTelemetry

public abstract ProbeMetaData addOpenControlObjectTelemetry(java.lang.String name)

Configures a telemetry that shows the number of open control objects. This only makes sense if your probe supports control objects and has called controlObjectView(boolean) with the argument true.

This only makes sense if the telemetry(boolean) method has been called with the argument true.

Parameters:

name - the name of the telemetry

Returns:

this instance

addCustomTelemetry

public abstract ProbeMetaData addCustomTelemetry(java.lang.String name,
                                                 Unit unit,
                                                 float factor)

Configures a custom telemetry. Telemetry values are sampled every second by calls to TelemetryProbe.fillTelemetryData(ProbeContext, int[]). The order of the invocations of this configuration method define the indices in the data array of the sampling method.

This only makes sense if the telemetry(boolean) method has been called with the argument true.

Parameters:

name - the name of the telemetry

unit - the unit of the measurement

factor - the number by which the measurements should be divided to get the numeric value for the vertical axis. If your measurements directly correspond to the selected unit, pass 1f.

Returns:

this instance

addAdditionalData

public abstract ProbeMetaData addAdditionalData(java.lang.String name,
                                                DataType dataType)

Configures an additional data column for probe events. Additional data is set by a call to ProbeEvent.additionalData(Object[]). The order of the invocations of this configuration method define the indices in the data array of the additionalData method.

This only makes sense if the events(boolean) method has been called with the argument true.

Parameters:

name - the name of the additional data column. This is displayed as the column header in the events view.

dataType - the data type of the additional data column

Returns:

this instance

addAdditionalControlObjectData

public abstract ProbeMetaData addAdditionalControlObjectData(java.lang.String name,
                                                             DataType dataType,
                                                             boolean nested)

Configures an additional data column for control objects. Additional data is set when control objects are opened with a call to ProbeContext.createOpenEvent(String, Object, Object[]) or ProbeContext.createOpenEvent(String, Object, Object[]). The order of the invocations of this configuration method define the indices in the data array of the createOpenEvent methods.

This only makes sense if the controlObjectView(boolean) method has been called with the argument true.

Parameters:

name - the name of the additional data column. This is displayed as the column header in the control objects view.

dataType - the data type of the additional data column

nested - If the column should be displayed in a nested table. This makes sense if the data is more for debugging purposes, contains very long text values or if you have a lot of additional data columns. For example, the built-in process probe shows several columns in a nested table.

Returns:

this instance

customTypeNames

public abstract ProbeMetaData customTypeNames(java.lang.String[] typeNames)

Configures the custom event types and their names. The index in the array becomes the ID of the custom event type and is used in calls to ProbeContext.createCustomEvent(String, int, Object) and InterceptorContext.startCustomState(Object, int). Custom events that are associated with control objects are also shown in the time line view in the way the horizontal bar of a control object is colored along the time axis. To configure the colors of custom events, call customColors(int[]).

Parameters:

typeNames - the names of the custom events. Not that the index in the array becomes the ID of the custom event.

Returns:

this instance

customColors

public abstract ProbeMetaData customColors(int[] customColors)

Configures the colors of the custom events in the time line view.

Parameters:

customColors - the colors as RGB values. The RGB value is the result of the getRGB() method on a java.awt.Color object. The array index of each color corresponds to the custom event index in the call to customTypeNames(String[]).

Returns:

this instance

See Also:

customTypeNames(String[])

openTypeName

public abstract ProbeMetaData openTypeName(java.lang.String name)

Sets the name of the automatic event type for the opening of a control object. This name is displayed in the event type selector of control object and events view as well as in the event type column of the events view. For example, the file probe sets this value to "File opened".

This only makes sense if the controlObjectView(boolean) method has been called with the argument true.

Parameters:

name - the name of the event type

Returns:

this instance

See Also:

closeTypeName(String)

closeTypeName

public abstract ProbeMetaData closeTypeName(java.lang.String name)

Sets the name of the automatic event type for the closing of a control object. This name is displayed in the event type selector of control object and events view as well as in the event type column of the events view. For example, the file probe sets this value to "File closed".

This only makes sense if the controlObjectView(boolean) method has been called with the argument true.

Parameters:

name - the name of the event type

Returns:

this instance

See Also:

(String)