# probe-injected-api

Content of the MCP resource `jprofiler://api/probe-injected` of the JProfiler MCP server, see the [tool and resource reference](../tools.md) for the full list of tools and resources.

# Injected probe API

API reference of `com.jprofiler.api.probe.injected` for writing injected custom probes: the `@Probe`
annotation, the interception declarations in the `interception` package, the injected parameter
annotations in the `parameter` package and the telemetry annotations. Read `jprofiler://probes/custom`
first for the embedded/injected decision, build setup, deployment and recording.

## Types

Flat alphabetical index of every type in the API. Use this when you know the qualified name and want to skip package navigation.

| Qualified name | Kind | File |
|---|---|---|
| `com.jprofiler.api.probe.injected.ControlObjectName` | annotation | [ControlObjectName](#com-jprofiler-api-probe-injected-controlobjectname) |
| `com.jprofiler.api.probe.injected.Payload` | interface | [Payload](#com-jprofiler-api-probe-injected-payload) |
| `com.jprofiler.api.probe.injected.Probe` | annotation | [Probe](#com-jprofiler-api-probe-injected-probe) |
| `com.jprofiler.api.probe.injected.ProbeContext` | interface | [ProbeContext](#com-jprofiler-api-probe-injected-probecontext) |
| `com.jprofiler.api.probe.injected.ThreadState` | enum | [ThreadState](#com-jprofiler-api-probe-injected-threadstate) |
| `com.jprofiler.api.probe.injected.TypeCustomizer` | interface | [TypeCustomizer](#com-jprofiler-api-probe-injected-typecustomizer) |
| `com.jprofiler.api.probe.injected.interception.AdditionalInterception` | annotation | [AdditionalInterception](#com-jprofiler-api-probe-injected-interception-additionalinterception) |
| `com.jprofiler.api.probe.injected.interception.Interception` | annotation | [Interception](#com-jprofiler-api-probe-injected-interception-interception) |
| `com.jprofiler.api.probe.injected.interception.InvocationType` | enum | [InvocationType](#com-jprofiler-api-probe-injected-interception-invocationtype) |
| `com.jprofiler.api.probe.injected.interception.MethodSpec` | annotation | [MethodSpec](#com-jprofiler-api-probe-injected-interception-methodspec) |
| `com.jprofiler.api.probe.injected.interception.PayloadInterception` | annotation | [PayloadInterception](#com-jprofiler-api-probe-injected-interception-payloadinterception) |
| `com.jprofiler.api.probe.injected.interception.SplitInterception` | annotation | [SplitInterception](#com-jprofiler-api-probe-injected-interception-splitinterception) |
| `com.jprofiler.api.probe.injected.parameter.DeclaringClass` | annotation | [DeclaringClass](#com-jprofiler-api-probe-injected-parameter-declaringclass) |
| `com.jprofiler.api.probe.injected.parameter.ExceptionValue` | annotation | [ExceptionValue](#com-jprofiler-api-probe-injected-parameter-exceptionvalue) |
| `com.jprofiler.api.probe.injected.parameter.Parameter` | annotation | [Parameter](#com-jprofiler-api-probe-injected-parameter-parameter) |
| `com.jprofiler.api.probe.injected.parameter.ReturnValue` | annotation | [ReturnValue](#com-jprofiler-api-probe-injected-parameter-returnvalue) |
| `com.jprofiler.api.probe.injected.parameter.ThisValue` | annotation | [ThisValue](#com-jprofiler-api-probe-injected-parameter-thisvalue) |
| `com.jprofiler.api.probe.injected.telemetry.Telemetry` | annotation | [Telemetry](#com-jprofiler-api-probe-injected-telemetry-telemetry) |
| `com.jprofiler.api.probe.injected.telemetry.TelemetryFormat` | annotation | [TelemetryFormat](#com-jprofiler-api-probe-injected-telemetry-telemetryformat) |
| `com.jprofiler.api.probe.injected.telemetry.TelemetryUnit` | enum | [TelemetryUnit](#com-jprofiler-api-probe-injected-telemetry-telemetryunit) |

## <a id="package-com-jprofiler-api-probe-injected"></a>Package `com.jprofiler.api.probe.injected`

Contains the classes for creating an injected probe.

**Purpose of injected probes**

Please read the "Probe concepts" chapter in the documentation (directory `$JPROFILER_HOME/doc`) for
an overview on the different types of custom probes in JProfiler and the "Injected probes" chapter
for an extended discussion of injected probes.

Injected probes allow you to add functionality similar to the built-in probes in JProfiler. In contrast to
the "embedded" probe API, the "injected" probe API monitors software components whose source code is not under your control.
If you develop software like a container or a database driver and want to make JProfiler aware of its high-level semantics,
use the embedded probe API instead.

**Getting started**

To define an injected probe, annotate a class with [`Probe`](#com-jprofiler-api-probe-injected-probe). Such a probe class can
contain public static methods annotated with
[`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception),
[`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception), [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception),
[`ControlObjectName`](#com-jprofiler-api-probe-injected-controlobjectname) and [`Telemetry`](#com-jprofiler-api-probe-injected-telemetry-telemetry).

To get started with writing injected probes, have a look at the `$JPROFILER_HOME/api/samples/simple-injected-probe`
example project. Open the gradle build file `build.gradle` in an editor for instructions on how to run it.

**JAR file and dependency**

All classes in this package are contained in `$JPROFILER_HOME/api/jprofiler-probe-injected.jar`.
The injected probe API is also available as a dependency. In the snippets below, "VERSION"
should be replaced with the corresponding JProfiler version.

**Maven**

```
<dependency>
  <groupId>com.jprofiler</groupId>
  <artifactId>jprofiler-probe-injected</artifactId>
  <version>VERSION</version>
</dependency>
```

**Gradle**

```
dependencies {
  implementation group: 'com.jprofiler', name: 'jprofiler-probe-injected', version: 'VERSION'
}
```

**Deployment**

To load injected custom probes, pass

```
     -Djprofiler.probeClassPath=...
```

to the profiled JVM. The probe classpath can contain directories and JAR files, separated with the path separator
(';' for Windows and ':' for other platforms). Note that the custom probe classes must not be on the class path.
The profiling agent will scan the probe classpath and find all probe definitions.

Alternatively, you can set

```
     -Djprofiler.customProbes=...
```

to a comma-separated list of fully qualified class names that will be loaded from the class path.

**License**

Classes in this package and its sub-packages are licensed under the Apache License, version 2.0.

### <a id="com-jprofiler-api-probe-injected-controlobjectname"></a>ControlObjectName

Import: `import com.jprofiler.api.probe.injected.ControlObjectName;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@interface ControlObjectName implements Annotation
```

Marks an optional method in your probe that will be called for previously unknown control objects. Control objects can be specified
with [`ProbeContext.createPayload`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum). The method must be public and static with a single parameter
of type `Object` and return a `String`.

Usually, control objects should be opened with [`ProbeContext.openControlObject`](#com-jprofiler-api-probe-injected-probecontext-opencontrolobject-object-string)

### <a id="com-jprofiler-api-probe-injected-payload"></a>Payload

Import: `import com.jprofiler.api.probe.injected.Payload;`

```java
interface Payload
```

Payload type with enhanced functionality. To use this functionality, your probe method must return instances of this type instead of `String`, declare a
parameter with type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) to get a context instance and call [`ProbeContext.createPayload`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum) to create a payload that it can return.

Do not create your own subtypes.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`getName()`](#com-jprofiler-api-probe-injected-payload-getname) | `String` | The name for this payload. |
| [`getEventType()`](#com-jprofiler-api-probe-injected-payload-geteventtype) | `Enum<?>` | The type of the payload. |
| [`getControlObject()`](#com-jprofiler-api-probe-injected-payload-getcontrolobject) | `Object` | The control object for this payload. |

<a id="com-jprofiler-api-probe-injected-payload-getname"></a>##### getName()

```java
String getName()
```

The name for this payload.


**Returns:** the name or `null` if none was provided yet

<a id="com-jprofiler-api-probe-injected-payload-geteventtype"></a>##### getEventType()

```java
Enum<?> getEventType()
```

The type of the payload. One of the enum constants of [`Probe.customTypes`](#com-jprofiler-api-probe-injected-probe-customtypes).


**Returns:** the type or `null` if none was provided

<a id="com-jprofiler-api-probe-injected-payload-getcontrolobject"></a>##### getControlObject()

```java
Object getControlObject()
```

The control object for this payload.


**Returns:** the control object or `null` if none was provided

### <a id="com-jprofiler-api-probe-injected-probe"></a>Probe

Import: `import com.jprofiler.api.probe.injected.Probe;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@interface Probe implements Annotation
```

Marks a class that defines an injected probe and parametrizes the probe. The probe class will be scanned for public static methods that are annotated with
[`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception), [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception), [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception), [`ControlObjectName`](#com-jprofiler-api-probe-injected-controlobjectname) and [`Telemetry`](#com-jprofiler-api-probe-injected-telemetry-telemetry).

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `name` | `String` | — | The name of the probe in the JProfiler UI. |
| `description` | `String` | `""` | An optional description of this probe. |
| `events` | `boolean` | `true` | Configures if this probe shows an events view in the JProfiler UI. |
| `controlObjects` | `boolean` | `false` | Configures if this probe shows the timeline and control objects views in the JProfiler UI. |
| `defaultTelemetries` | `boolean` | `true` | Configures if this probe should record the "Events", "Average Duration" and - if control objects are recorded - the "Recorded Open Control Objects" telemetries. |
| `customTypes` | `Class<? extends Enum>` | `java.lang.Enum.class` | You can specify custom types for events. |

<a id="com-jprofiler-api-probe-injected-probe-name"></a>##### name

The name of the probe in the JProfiler UI.
In the JProfiler UI, this string is used for the view name in the view selector below the "JEE & probes" section.

<a id="com-jprofiler-api-probe-injected-probe-description"></a>##### description

An optional description of this probe.
It is shown in the probe view below the probe name.

<a id="com-jprofiler-api-probe-injected-probe-events"></a>##### events

Configures if this probe shows an events view in the JProfiler UI.

<a id="com-jprofiler-api-probe-injected-probe-controlobjects"></a>##### controlObjects

Configures if this probe shows the timeline and control objects views in the JProfiler UI.

You must make use of [`ProbeContext.createPayload`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum) to associate control objects with payloads.

<a id="com-jprofiler-api-probe-injected-probe-defaulttelemetries"></a>##### defaultTelemetries

Configures if this probe should record the "Events", "Average Duration" and - if control objects are recorded - the "Recorded Open Control Objects" telemetries.

<a id="com-jprofiler-api-probe-injected-probe-customtypes"></a>##### customTypes

You can specify custom types for events. If control objects are recorded, the same types are used for the associated control object states.
Specify an `Enum` class with all your states as constants. The `toString()` method is used for
the event display name. You can further customize your events by implementing [`TypeCustomizer`](#com-jprofiler-api-probe-injected-typecustomizer) in the enum class.

### <a id="com-jprofiler-api-probe-injected-probecontext"></a>ProbeContext

Import: `import com.jprofiler.api.probe.injected.ProbeContext;`

```java
interface ProbeContext
```

An interface for enhanced probe functionality. In methods annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception), [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) and [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception),
you can declare a parameter of this type in any position in order to get an instance of this interface.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`openControlObject(Object, String)`](#com-jprofiler-api-probe-injected-probecontext-opencontrolobject-object-string) | `void` | Records an open event for a control object and assigns a name to it. |
| [`closeControlObject(Object)`](#com-jprofiler-api-probe-injected-probecontext-closecontrolobject-object) | `void` | Closes a control object. |
| [`createPayload(String, Object, Enum<?>)`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum) | `Payload` | Creates an enhanced payload object with type and control object info. |
| [`createPayloadWithDeferredName(Object, Enum<?>)`](#com-jprofiler-api-probe-injected-probecontext-createpayloadwithdeferredname-object-enum) | `Payload` | Creates an enhanced payload object with type and control object info whose name you don't know yet. |
| [`getOuterPayload()`](#com-jprofiler-api-probe-injected-probecontext-getouterpayload) | `Payload` | Retrieves the payload information that has been created by an outer interception, either through recursion or by a different intercepted method. |
| [`restartTiming()`](#com-jprofiler-api-probe-injected-probecontext-restarttiming) | `void` | If a payload is currently recorded by an outer interception, restart timing. |
| [`restartTimingAndLocation()`](#com-jprofiler-api-probe-injected-probecontext-restarttimingandlocation) | `void` | If a payload is currently recorded by an outer interception, restart timing and set the call tree to the location of the latest [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) or the latest [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) with [`SplitInterception.payloads`](#com-jprofiler-api-probe-injected-interception-splitinterception-payloads) set to `true`. |
| [`isRecording()`](#com-jprofiler-api-probe-injected-probecontext-isrecording) | `boolean` | Returns the recording state of the probe. |

<a id="com-jprofiler-api-probe-injected-probecontext-opencontrolobject-object-string"></a>##### openControlObject(Object, String)

```java
void openControlObject(Object controlObject, String name)
```

Records an open event for a control object and assigns a name to it. The control object will be displayed in the control objects view and the timeline.
You must set [`Probe.controlObjects`](#com-jprofiler-api-probe-injected-probe-controlobjects) to `true` to enable control object recording as a capability for the probe.

If you don't use this method and a previously unknown control object is used in a [`ProbeContext.createPayload`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum) call and
you have annotated a method in your probe class with [`ControlObjectName`](#com-jprofiler-api-probe-injected-controlobjectname), that method will be called to create a name for the new control object.
No open event will be created in the events view in that case.


**Parameters:**

- `controlObject` — the control object
- `name` — the name of the control object

<a id="com-jprofiler-api-probe-injected-probecontext-closecontrolobject-object"></a>##### closeControlObject(Object)

```java
void closeControlObject(Object controlObject)
```

Closes a control object. If the control object is not currently open, this method has no effect.


**Parameters:**

- `controlObject` — the control object

<a id="com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum"></a>##### createPayload(String, Object, Enum<?>)

```java
Payload createPayload(String name, Object controlObject, Enum<?> type)
```

Creates an enhanced payload object with type and control object info. You can use the created object in
- a method returning a [`Payload`](#com-jprofiler-api-probe-injected-payload) that is either annotated with [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) and
where [`PayloadInterception.invokeOn`](#com-jprofiler-api-probe-injected-interception-payloadinterception-invokeon) is set to [`InvocationType.ENTER`](#com-jprofiler-api-probe-injected-interception-invocationtype-enter)
- a method with [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) and [`SplitInterception.payloads`](#com-jprofiler-api-probe-injected-interception-splitinterception-payloads) set to `true`

If you don't want to assign states or control objects, you can just return the name as a `String` directly.


**Parameters:**

- `name` — the name of the recorded payload. If `null`, the payload recording will be discarded.
- `type` — the payload type. Must be an object of your custom enum class registered with [`Probe.customTypes`](#com-jprofiler-api-probe-injected-probe-customtypes) or `null`.
- `controlObject` — the control object this payload belongs to or `null`. If control objects should be recorded, you have to set [`Probe.controlObjects`](#com-jprofiler-api-probe-injected-probe-controlobjects) to `true`.

**Returns:** a [`Payload`](#com-jprofiler-api-probe-injected-payload) instance to be returned by your interception method

<a id="com-jprofiler-api-probe-injected-probecontext-createpayloadwithdeferredname-object-enum"></a>##### createPayloadWithDeferredName(Object, Enum<?>)

```java
Payload createPayloadWithDeferredName(Object controlObject, Enum<?> type)
```

Creates an enhanced payload object with type and control object info whose name you don't know yet. You can use
the created object in a method returning a [`Payload`](#com-jprofiler-api-probe-injected-payload) that is annotated with [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) and
where [`PayloadInterception.invokeOn`](#com-jprofiler-api-probe-injected-interception-payloadinterception-invokeon) is set to [`InvocationType.ENTER`](#com-jprofiler-api-probe-injected-interception-invocationtype-enter).

To supply the name at a later point, you have to define a method right below the current method, annotate it with [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception) and return a `String`.

If you don't want to assign states or control objects, you can set [`PayloadInterception.invokeOn`](#com-jprofiler-api-probe-injected-interception-payloadinterception-invokeon) to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) and return the name as a `String` directly.


**Parameters:**

- `type` — the payload type. Must be an object of your custom enum class registered with [`Probe.customTypes`](#com-jprofiler-api-probe-injected-probe-customtypes) or `null`.
- `controlObject` — the control object this payload belongs to or `null`. If control objects should be recorded, you have to set [`Probe.controlObjects`](#com-jprofiler-api-probe-injected-probe-controlobjects) to `true`.

**Returns:** a [`Payload`](#com-jprofiler-api-probe-injected-payload) instance to be returned by your interception method

<a id="com-jprofiler-api-probe-injected-probecontext-getouterpayload"></a>##### getOuterPayload()

```java
Payload getOuterPayload()
```

Retrieves the payload information that has been created by an outer interception, either through recursion or by a different intercepted method.

If your inner interception method is annotated with [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception), you can return this payload to keep the payload information unchanged. A [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) won't
change an outer payload, so this does not apply for nested splits.


**Returns:** the current payload or `null` if there is no current payload defined.

<a id="com-jprofiler-api-probe-injected-probecontext-restarttiming"></a>##### restartTiming()

```java
void restartTiming()
```

If a payload is currently recorded by an outer interception, restart timing.

<a id="com-jprofiler-api-probe-injected-probecontext-restarttimingandlocation"></a>##### restartTimingAndLocation()

```java
void restartTimingAndLocation()
```

If a payload is currently recorded by an outer interception, restart timing and set the call tree to the location of the latest [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) or the latest [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) with [`SplitInterception.payloads`](#com-jprofiler-api-probe-injected-interception-splitinterception-payloads) set to `true`.

<a id="com-jprofiler-api-probe-injected-probecontext-isrecording"></a>##### isRecording()

```java
boolean isRecording()
```

Returns the recording state of the probe.

Methods annotated with [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) are only called when probe recording is turned on. Methods annotated with [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception)
are called when CPU or allocation recording is turned on. If [`SplitInterception.payloads`](#com-jprofiler-api-probe-injected-interception-splitinterception-payloads) is set to `true`, they are also called when only probe recording is turned on.
Methods annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception) are always called.


**Returns:** `true` if your probe is being recorded

### <a id="com-jprofiler-api-probe-injected-threadstate"></a>ThreadState

Import: `import com.jprofiler.api.probe.injected.ThreadState;`

```java
public final enum ThreadState
```

Allows you to override the thread state recorded in JProfiler.

You can nest calls to [`ThreadState.enter`](#com-jprofiler-api-probe-injected-threadstate-enter) and [`ThreadState.exit`](#com-jprofiler-api-probe-injected-threadstate-exit), but only the outermost call is used for recording.

It is very important that a matching [`ThreadState.exit`](#com-jprofiler-api-probe-injected-threadstate-exit) is always called, so if you call [`ThreadState.enter`](#com-jprofiler-api-probe-injected-threadstate-enter) in an [`Interception`](#com-jprofiler-api-probe-injected-interception-interception) with [`Interception.invokeOn`](#com-jprofiler-api-probe-injected-interception-interception-invokeon) set to [`InvocationType.ENTER`](#com-jprofiler-api-probe-injected-interception-invocationtype-enter),
you must always define a method right below it that is annotated with [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception) with [`AdditionalInterception.value`](#com-jprofiler-api-probe-injected-interception-additionalinterception-value) set to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) where you call [`ThreadState.exit`](#com-jprofiler-api-probe-injected-threadstate-exit).

#### Constants

<a id="com-jprofiler-api-probe-injected-threadstate-runnable"></a>##### RUNNABLE

The current thread is runnable.

<a id="com-jprofiler-api-probe-injected-threadstate-waiting"></a>##### WAITING

The current thread is waiting.

<a id="com-jprofiler-api-probe-injected-threadstate-blocked"></a>##### BLOCKED

The current thread is blocked on a monitor.

<a id="com-jprofiler-api-probe-injected-threadstate-netio"></a>##### NETIO

The current thread is in a Net IO operation.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`values()`](#com-jprofiler-api-probe-injected-threadstate-values) | `ThreadState[]` |  |
| [`valueOf(String)`](#com-jprofiler-api-probe-injected-threadstate-valueof-string) | `ThreadState` |  |
| [`enter()`](#com-jprofiler-api-probe-injected-threadstate-enter) | `void` | Enters a thread state. |
| [`exit()`](#com-jprofiler-api-probe-injected-threadstate-exit) | `void` | Exits the current override state and resets the state to the value reported by the JVM. |

<a id="com-jprofiler-api-probe-injected-threadstate-values"></a>##### values()

```java
public static ThreadState[] values()
```

<a id="com-jprofiler-api-probe-injected-threadstate-valueof-string"></a>##### valueOf(String)

```java
public static ThreadState valueOf(String name)
```

<a id="com-jprofiler-api-probe-injected-threadstate-enter"></a>##### enter()

```java
public void enter()
```

Enters a thread state. This state will be recorded until the matching exit is called.

<a id="com-jprofiler-api-probe-injected-threadstate-exit"></a>##### exit()

```java
public static void exit()
```

Exits the current override state and resets the state to the value reported by the JVM.

### <a id="com-jprofiler-api-probe-injected-typecustomizer"></a>TypeCustomizer

Import: `import com.jprofiler.api.probe.injected.TypeCustomizer;`

```java
interface TypeCustomizer
```

Interface to further customize event enums configured with [`Probe.customTypes`](#com-jprofiler-api-probe-injected-probe-customtypes).
Your enum class can implement this interface to customize the color of your types.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`getColor()`](#com-jprofiler-api-probe-injected-typecustomizer-getcolor) | `int` | The color of your enum constant. |

<a id="com-jprofiler-api-probe-injected-typecustomizer-getcolor"></a>##### getColor()

```java
int getColor()
```

The color of your enum constant.


**Returns:** the RGB int value of a color, for example `0xCCAA00`

## <a id="package-com-jprofiler-api-probe-injected-interception"></a>Package `com.jprofiler.api.probe.injected.interception`

Contains the annotations for specifying which methods should be intercepted.

### <a id="com-jprofiler-api-probe-injected-interception-additionalinterception"></a>AdditionalInterception

Import: `import com.jprofiler.api.probe.injected.interception.AdditionalInterception;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@interface AdditionalInterception implements Annotation
```

Marks a probe method to be called at an additional point of the previously declared interception. The source file method order will be used to determine the previous interception that this additional interception belongs to.

The annotated method must be public and static. If the main interception is a [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) that returns [`Payload`](#com-jprofiler-api-probe-injected-payload), the probe method annotated with `AdditionalInterception` can return a `String` to update the payload name. Otherwise, the probe method must return void.

You can get information from the intercepted method like parameter values, the instance or the return value by declaring parameters annotated with
the annotations from the [com.jprofiler.api.probe.injected.parameter]({@docRoot}/com/jprofiler/api/probe/injected/parameter/package-summary.html) package. You can also declare a parameter of type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) to
open or close control objects or check if the probe is currently being recorded.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `value` | `InvocationType` | — | The point at which the annotated probe method is invoked. |

<a id="com-jprofiler-api-probe-injected-interception-additionalinterception-value"></a>##### value

The point at which the annotated probe method is invoked.

### <a id="com-jprofiler-api-probe-injected-interception-interception"></a>Interception

Import: `import com.jprofiler.api.probe.injected.interception.Interception;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@interface Interception implements Annotation
```

Declares an interception that does not split the call tree or create a payload. The annotated probe method must be public and static and return void.

You can get information from the intercepted method like parameter values, the instance or the return value by declaring parameters annotated with
the annotations from the [com.jprofiler.api.probe.injected.parameter]({@docRoot}/com/jprofiler/api/probe/injected/parameter/package-summary.html) package. You can also declare a parameter of type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) to
open or close control objects or check if the probe is currently being recorded.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `invokeOn` | `InvocationType` | — | The point at which the annotated probe method is invoked. |
| `method` | `MethodSpec` | — | Specifies the method that should be intercepted. |
| `reentrant` | `boolean` | `true` | Indicates if your interception is reentrant. |

<a id="com-jprofiler-api-probe-injected-interception-interception-invokeon"></a>##### invokeOn

The point at which the annotated probe method is invoked.

<a id="com-jprofiler-api-probe-injected-interception-interception-method"></a>##### method

Specifies the method that should be intercepted.

<a id="com-jprofiler-api-probe-injected-interception-interception-reentrant"></a>##### reentrant

Indicates if your interception is reentrant. If `false`, the probe method will not be called for recursive invocations of the intercepted method.

### <a id="com-jprofiler-api-probe-injected-interception-invocationtype"></a>InvocationType

Import: `import com.jprofiler.api.probe.injected.interception.InvocationType;`

```java
public final enum InvocationType
```

Specifies the point at which the probe method is invoked.

#### Constants

<a id="com-jprofiler-api-probe-injected-interception-invocationtype-enter"></a>##### ENTER

The probe method will be called before any code of the intercepted method is called. You cannot use [`ReturnValue`](#com-jprofiler-api-probe-injected-parameter-returnvalue) or [`ExceptionValue`](#com-jprofiler-api-probe-injected-parameter-exceptionvalue) parameters
for methods of this type.

<a id="com-jprofiler-api-probe-injected-interception-invocationtype-exit"></a>##### EXIT

The probe method will be called when the intercepted method exits, either by returning normally or by throwing an exception. You can use both
[`ReturnValue`](#com-jprofiler-api-probe-injected-parameter-returnvalue) and [`ExceptionValue`](#com-jprofiler-api-probe-injected-parameter-exceptionvalue) parameters for methods of this type. If the intercepted method returns normally, the [`ExceptionValue`](#com-jprofiler-api-probe-injected-parameter-exceptionvalue) parameter will be `null`.
If the method throws an exception, the [`ReturnValue`](#com-jprofiler-api-probe-injected-parameter-returnvalue) parameter will be `null`.

This type cannot be used for constructors.

<a id="com-jprofiler-api-probe-injected-interception-invocationtype-return"></a>##### RETURN

The probe method will be called when the intercepted method returns normally. You can use a [`ReturnValue`](#com-jprofiler-api-probe-injected-parameter-returnvalue) parameter, but no [`ExceptionValue`](#com-jprofiler-api-probe-injected-parameter-exceptionvalue) parameter for methods of this type.

<a id="com-jprofiler-api-probe-injected-interception-invocationtype-exception"></a>##### EXCEPTION

The probe method will be called when the intercepted method throws an exception. You can use an [`ExceptionValue`](#com-jprofiler-api-probe-injected-parameter-exceptionvalue) parameter, but no [`ReturnValue`](#com-jprofiler-api-probe-injected-parameter-returnvalue) parameter for methods of this type.

This type cannot be used for constructors.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`values()`](#com-jprofiler-api-probe-injected-interception-invocationtype-values) | `InvocationType[]` |  |
| [`valueOf(String)`](#com-jprofiler-api-probe-injected-interception-invocationtype-valueof-string) | `InvocationType` |  |

<a id="com-jprofiler-api-probe-injected-interception-invocationtype-values"></a>##### values()

```java
public static InvocationType[] values()
```

<a id="com-jprofiler-api-probe-injected-interception-invocationtype-valueof-string"></a>##### valueOf(String)

```java
public static InvocationType valueOf(String name)
```

### <a id="com-jprofiler-api-probe-injected-interception-methodspec"></a>MethodSpec

Import: `import com.jprofiler.api.probe.injected.interception.MethodSpec;`

```java
@interface MethodSpec implements Annotation
```

Specification of the intercepted method.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `className` | `String` | — | The fully qualified name of the highest type in the class hierarchy where the method is implemented. |
| `methodName` | `String` | — | The name of the method. |
| `parameterTypes` | `String[]` | — | The array of all parameter types that the method declares. |
| `returnType` | `String` | — | The return type that the method declares. |
| `subtypes` | `boolean` | `false` | If `false`, only the method contained in [`MethodSpec.className`](#com-jprofiler-api-probe-injected-interception-methodspec-classname) will be instrumented, but not in derived classes. |

<a id="com-jprofiler-api-probe-injected-interception-methodspec-classname"></a>##### className

The fully qualified name of the highest type in the class hierarchy where the method is implemented. Can be an empty string if you would like to instrument all methods
with the given name and signature. Packages are separated with dots, inner classes with '$'.

<a id="com-jprofiler-api-probe-injected-interception-methodspec-methodname"></a>##### methodName

The name of the method. If you would like to instrument a constructor, use `<init>`.

<a id="com-jprofiler-api-probe-injected-interception-methodspec-parametertypes"></a>##### parameterTypes

The array of all parameter types that the method declares. The types must be fully qualified. Packages are separated with dots, inner classes with '$'.
Arrays are specified with a trailing '[]'.
Generic types must be erased (`java.util.List<T>` -> `java.util.List`).
Type parameters must be replaced by their upper bounds (`java.lang.Object` for `<T>`, `java.util.List` for `<T extends List<U>>`).

<a id="com-jprofiler-api-probe-injected-interception-methodspec-returntype"></a>##### returnType

The return type that the method declares. The type must be fully qualified. Packages are separated with dots, inner classes with '$'.
Arrays are specified with a trailing '[]'.
Generic types must be erased (`java.util.List<T>` -> `java.util.List`).
Type parameters must be replaced by their upper bounds (`java.lang.Object` for `<T>`, `java.util.List` for `<T extends List<U>>`).

<a id="com-jprofiler-api-probe-injected-interception-methodspec-subtypes"></a>##### subtypes

If `false`, only the method contained in [`MethodSpec.className`](#com-jprofiler-api-probe-injected-interception-methodspec-classname) will be instrumented, but not in derived classes.
If `true`, the matching methods in [`MethodSpec.className`](#com-jprofiler-api-probe-injected-interception-methodspec-classname) and all its subtypes will be instrumented.

### <a id="com-jprofiler-api-probe-injected-interception-payloadinterception"></a>PayloadInterception

Import: `import com.jprofiler.api.probe.injected.interception.PayloadInterception;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@interface PayloadInterception implements Annotation
```

Declares an interception that creates a payload. The annotated probe method must be public and static and return `String` or [`Payload`](#com-jprofiler-api-probe-injected-payload).

You can get information from the intercepted method like parameter values, the instance or the return value by declaring parameters annotated with
the annotations from the [com.jprofiler.api.probe.injected.parameter]({@docRoot}/com/jprofiler/api/probe/injected/parameter/package-summary.html) package. You can also declare a parameter of type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) to
open or close control objects or create payloads with enhanced functionality.

If you return a [`Payload`](#com-jprofiler-api-probe-injected-payload) to specify control objects or custom event types, you must declare a parameter of type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) and create the returned object with
[`ProbeContext.createPayload`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum) or [`ProbeContext.createPayloadWithDeferredName`](#com-jprofiler-api-probe-injected-probecontext-createpayloadwithdeferredname-object-enum). The [`PayloadInterception.invokeOn`](#com-jprofiler-api-probe-injected-interception-payloadinterception-invokeon) argument must be set
to [`InvocationType.ENTER`](#com-jprofiler-api-probe-injected-interception-invocationtype-enter) in that case.

If you create a [`Payload`](#com-jprofiler-api-probe-injected-payload) with a deferred name because the payload name cannot be determined at method entry, you must declare a method directly below the current interception method,
annotate it with [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception) where [`AdditionalInterception.value`](#com-jprofiler-api-probe-injected-interception-additionalinterception-value) is set to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) and return a `String` from that method.

If you don't want to create a payload for the current invocation, the probe method can return `null`.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `invokeOn` | `InvocationType` | — | The point at which the annotated probe method is invoked. |
| `method` | `MethodSpec` | — | Specifies the method that should be intercepted. |
| `reentrant` | `boolean` | `false` | Indicates if your interception is reentrant. |
| `exceptionPayloads` | `boolean` | `false` | If payloads should also be recorded if the method throws an exception. |

<a id="com-jprofiler-api-probe-injected-interception-payloadinterception-invokeon"></a>##### invokeOn

The point at which the annotated probe method is invoked.

<a id="com-jprofiler-api-probe-injected-interception-payloadinterception-method"></a>##### method

Specifies the method that should be intercepted.

<a id="com-jprofiler-api-probe-injected-interception-payloadinterception-reentrant"></a>##### reentrant

Indicates if your interception is reentrant. If `false`, the probe method will not be called for recursive invocations of the intercepted method.

If `true`, the payload name (and the other information in [`Payload`](#com-jprofiler-api-probe-injected-payload)) returned by the subsequent inner calls will be used, but timing and call tree location will be used from the outermost call. You can use
[`ProbeContext.restartTiming`](#com-jprofiler-api-probe-injected-probecontext-restarttiming) and [`ProbeContext.restartTimingAndLocation`](#com-jprofiler-api-probe-injected-probecontext-restarttimingandlocation) to customize this behavior. If you want to retain the name from outer calls you can use [`ProbeContext.getOuterPayload`](#com-jprofiler-api-probe-injected-probecontext-getouterpayload).

<a id="com-jprofiler-api-probe-injected-interception-payloadinterception-exceptionpayloads"></a>##### exceptionPayloads

If payloads should also be recorded if the method throws an exception.
If [`PayloadInterception.invokeOn`](#com-jprofiler-api-probe-injected-interception-payloadinterception-invokeon) is set to [`InvocationType.EXCEPTION`](#com-jprofiler-api-probe-injected-interception-invocationtype-exception) or [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit),
JProfiler will always record payloads for exceptional exits.

### <a id="com-jprofiler-api-probe-injected-interception-splitinterception"></a>SplitInterception

Import: `import com.jprofiler.api.probe.injected.interception.SplitInterception;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@interface SplitInterception implements Annotation
```

Declares an interception that creates a split in the call tree and optionally an associated payload. The annotated probe method must be public and static and return `String` or [`Payload`](#com-jprofiler-api-probe-injected-payload).

You can get information from the intercepted method like parameter values or the instance by declaring parameters annotated with
the annotations from the [com.jprofiler.api.probe.injected.parameter]({@docRoot}/com/jprofiler/api/probe/injected/parameter/package-summary.html) package. You can also declare a parameter of type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) to
open or close control objects or check if the probe is currently being recorded.

If you return a [`Payload`](#com-jprofiler-api-probe-injected-payload) to specify control objects or custom event types, you must declare a parameter of type [`ProbeContext`](#com-jprofiler-api-probe-injected-probecontext) and create the returned object with
[`ProbeContext.createPayload`](#com-jprofiler-api-probe-injected-probecontext-createpayload-string-object-enum).

If you don't want to create a split for the current invocation, the probe method can return `null`.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `method` | `MethodSpec` | — | Specifies the method that should be intercepted. |
| `payloads` | `boolean` | `true` | If payloads should be created in addition to the call tree split. |
| `reentrant` | `boolean` | `false` | Indicates if your interception is reentrant. |
| `exceptionPayloads` | `boolean` | `false` | If payloads should also be recorded if the method throws an exception. |

<a id="com-jprofiler-api-probe-injected-interception-splitinterception-method"></a>##### method

Specifies the method that should be intercepted.

<a id="com-jprofiler-api-probe-injected-interception-splitinterception-payloads"></a>##### payloads

If payloads should be created in addition to the call tree split.

<a id="com-jprofiler-api-probe-injected-interception-splitinterception-reentrant"></a>##### reentrant

Indicates if your interception is reentrant. If `false`, the probe method will not be called for recursive invocations of the intercepted method and only one split will be created.

If `true`, splits will be nested, but only one payload will be created for the outermost call.

<a id="com-jprofiler-api-probe-injected-interception-splitinterception-exceptionpayloads"></a>##### exceptionPayloads

If payloads should also be recorded if the method throws an exception.

## <a id="package-com-jprofiler-api-probe-injected-parameter"></a>Package `com.jprofiler.api.probe.injected.parameter`

Contains the annotations for specifying the parameters of interception methods.

With the annotations in this package, methods annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception),
[`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) and [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception) can declare parameters to
receive further information from the intercepted method.

### <a id="com-jprofiler-api-probe-injected-parameter-declaringclass"></a>DeclaringClass

Import: `import com.jprofiler.api.probe.injected.parameter.DeclaringClass;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
@interface DeclaringClass implements Annotation
```

Assigns the class of the intercepted method to a parameter of a probe method. The probe method can be annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception), [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) or [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception).
The type of the annotated parameter must be `Class`.

### <a id="com-jprofiler-api-probe-injected-parameter-exceptionvalue"></a>ExceptionValue

Import: `import com.jprofiler.api.probe.injected.parameter.ExceptionValue;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
@interface ExceptionValue implements Annotation
```

Assigns the exception thrown by the intercepted method to a parameter of a probe method. The probe method can be annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) or [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception) whose
invocation type is set to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) or [`InvocationType.EXCEPTION`](#com-jprofiler-api-probe-injected-interception-invocationtype-exception). The type of the annotated parameter must be `Throwable`.

If the invocation type is set to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) and the instrumented method returns normally, the argument will be `null`.

### <a id="com-jprofiler-api-probe-injected-parameter-parameter"></a>Parameter

Import: `import com.jprofiler.api.probe.injected.parameter.Parameter;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
@interface Parameter implements Annotation
```

Assigns the argument with index [`Parameter.value`](#com-jprofiler-api-probe-injected-parameter-parameter-value) of the intercepted method to a parameter of a probe method. The probe method can be annotated with
[`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception), [`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) or [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception).
The type of the annotated parameter must be `Object` or the declared type of the parameter of the instrumented method. The declared type can only
be used if it can be resolved by the system class loader.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `value` | `int` | — | The zero-based index of the parameter |

<a id="com-jprofiler-api-probe-injected-parameter-parameter-value"></a>##### value

The zero-based index of the parameter

### <a id="com-jprofiler-api-probe-injected-parameter-returnvalue"></a>ReturnValue

Import: `import com.jprofiler.api.probe.injected.parameter.ReturnValue;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
@interface ReturnValue implements Annotation
```

Assigns the return value of the instrumented method to a parameter of a probe method. The probe method can be annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception) or [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception) whose
invocation type is set to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) or [`InvocationType.RETURN`](#com-jprofiler-api-probe-injected-interception-invocationtype-return). The type of the annotated parameter must be `Object` or the declared return type of the instrumented method. The declared type can only
be used if it can be resolved by the system class loader.

If the invocation type is set to [`InvocationType.EXIT`](#com-jprofiler-api-probe-injected-interception-invocationtype-exit) and the instrumented method throws an exception, the argument will be `null`.

### <a id="com-jprofiler-api-probe-injected-parameter-thisvalue"></a>ThisValue

Import: `import com.jprofiler.api.probe.injected.parameter.ThisValue;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
@interface ThisValue implements Annotation
```

Assigns the instance that the instrumented method was invoked on to a parameter of a probe method. The probe method can be annotated with [`Interception`](#com-jprofiler-api-probe-injected-interception-interception), [`PayloadInterception`](#com-jprofiler-api-probe-injected-interception-payloadinterception),
[`SplitInterception`](#com-jprofiler-api-probe-injected-interception-splitinterception) or [`AdditionalInterception`](#com-jprofiler-api-probe-injected-interception-additionalinterception). The type of the annotated parameter must be `Object` or the type given in [`MethodSpec.className`](#com-jprofiler-api-probe-injected-interception-methodspec-classname).
The declared type can only be used if it can be resolved by the system class loader.

If the instrumented method is a static method, the argument will be `null`. If the instrumented method is a constructor, the value will be `null` for [`InvocationType.ENTER`](#com-jprofiler-api-probe-injected-interception-invocationtype-enter) because
the super constructor has not been invoked yet.

## <a id="package-com-jprofiler-api-probe-injected-telemetry"></a>Package `com.jprofiler.api.probe.injected.telemetry`

Contains the classes for adding custom telemetries to an injected probe.

The [`Telemetry`](#com-jprofiler-api-probe-injected-telemetry-telemetry) annotation contains further information.

### <a id="com-jprofiler-api-probe-injected-telemetry-telemetry"></a>Telemetry

Import: `import com.jprofiler.api.probe.injected.telemetry.Telemetry;`

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
@interface Telemetry implements Annotation
```

Create a custom telemetry from the numeric return value of the annotated static method in a probe class.

Only public static parameterless methods can be used for creating custom telemetries, annotating instance methods or non-public
static methods will cause an error when the probe is registered.
The method must return a numeric value, either a primitive value like `int` or `double`, a
`java.math.BigDecimal` or a primitive wrapper instance like `java.lang.Integer` or `java.lang.Double`.

The method is called periodically on a dedicated thread. This may have implications for the requirements of
**thread safety** in your code. If the numeric value is calculated on the fly, access to the data structures
must be made thread-safe by making access to those data structures synchronized. Alternatively, you could
calculate a cached value when convenient and save it to a volatile atomic value, like an `int` or a
class from the `java.util.concurrent.atomic` package.

For example, the following code snippet defines a custom telemetry with the name "Connection count":

```
&#064;Telemetry("Connection count")
    public static int getConnectionCount() {
        return connectionCount;
    }
```

**Multiple lines in a single custom telemetry**

If you want to compare several measurements in the same telemetry, you can annotate multiple methods with the
same [`Telemetry.value`](#com-jprofiler-api-probe-injected-telemetry-telemetry-value) for the telemetry name, but with a different [`Telemetry.line`](#com-jprofiler-api-probe-injected-telemetry-telemetry-line) parameter.

For example:

```
&#064;Telemetry(value = "Queries", line = "Successful queries")
    public static int getSuccessCount() {
        return successCount;
    }
    &#064;Telemetry(value = "Queries", line = "Failed queries")
    public static int getErrorCount() {
        return errorCount;
    }
```

This will create a single custom telemetry with the name "Queries" and two data lines named
"Successful queries" and "Failed queries".

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `value` | `String` | — | The name of the telemetry. |
| `line` | `String` | `""` | The optional line name of the telemetry. |
| `format` | `TelemetryFormat` | `@com.jprofiler.api.probe.injected.telemetry.TelemetryFormat` | Optional display options for the telemetry. |

<a id="com-jprofiler-api-probe-injected-telemetry-telemetry-value"></a>##### value

The name of the telemetry. Give different names to different telemetries. Reuse the same name when annotating
different methods if you are creating a custom telemetry with multiple lines.
If only a single line is used, you can omit the "value" parameter name, as in

```
&#064;Telemetry("Connection count")
```

<a id="com-jprofiler-api-probe-injected-telemetry-telemetry-line"></a>##### line

The optional line name of the telemetry. Only specify this parameter if you're creating a telemetry with
multiple lines. See [`Telemetry`](#com-jprofiler-api-probe-injected-telemetry-telemetry) for an example.

<a id="com-jprofiler-api-probe-injected-telemetry-telemetry-format"></a>##### format

Optional display options for the telemetry.

### <a id="com-jprofiler-api-probe-injected-telemetry-telemetryformat"></a>TelemetryFormat

Import: `import com.jprofiler.api.probe.injected.telemetry.TelemetryFormat;`

```java
@interface TelemetryFormat implements Annotation
```

Display options for a [`Telemetry`](#com-jprofiler-api-probe-injected-telemetry-telemetry) annotation.
This annotation is used by the [`Telemetry.format`](#com-jprofiler-api-probe-injected-telemetry-telemetry-format) parameter.

#### Elements

| Element | Type | Default | Description |
|---|---|---|---|
| `value` | `TelemetryUnit` | `PLAIN` | The unit of the recorded values. |
| `scale` | `int` | `0` | A scaling factor for the telemetry. |
| `stacked` | `boolean` | `false` | Determines whether multiple lines in a telemetry should be stacked into an area graph. |

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryformat-value"></a>##### value

The unit of the recorded values. By default, telemetries are unitless.

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryformat-scale"></a>##### scale

A scaling factor for the telemetry. In the UI, recorded values will be multiplied with `10^-scale`.

In JProfiler, probe telemetry data is stored in 32-bit ints. So this is especially useful for telemetries that
will show higher values than 2^31. For example, if you use the
[`TelemetryUnit.BYTES`](#com-jprofiler-api-probe-injected-telemetry-telemetryunit-bytes) you can return kB instead and set the scale to `-3`.

This is also useful to show fractional values. For example, if you want to show a percentage with two decimal digits,
the returned value should be the percentage times 100 and the scale parameter should be set to `2`.

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryformat-stacked"></a>##### stacked

Determines whether multiple lines in a telemetry should be stacked into an area graph.
By default, multiple telemetry lines are not stacked. An example of a stacked graph is the "Heap usage" telemetry.

### <a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit"></a>TelemetryUnit

Import: `import com.jprofiler.api.probe.injected.telemetry.TelemetryUnit;`

```java
public final enum TelemetryUnit
```

Telemetry unit used in the [`TelemetryFormat`](#com-jprofiler-api-probe-injected-telemetry-telemetryformat) annotation.

#### Constants

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-plain"></a>##### PLAIN

The telemetry value is a unitless number.

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-per-second"></a>##### PER_SECOND

The telemetry value has the unit "per second".

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-percent"></a>##### PERCENT

The telemetry value has the unit "percent".

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-milliseconds"></a>##### MILLISECONDS

The telemetry value has the unit "milliseconds". Conversion into higher unit prefixes such as seconds
is done automatically as required.

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-microseconds"></a>##### MICROSECONDS

The telemetry value has the unit "microseconds". Conversion into higher unit prefixes such as seconds
is done automatically as required.

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-bytes"></a>##### BYTES

The telemetry value has the unit "bytes". Conversion into higher unit prefixes such as kB, MB or GB
is done automatically as required.

In JProfiler, probe telemetry data is stored in 32-bit ints. If you expect higher values than 2^31 bytes, you can
for example return kB instead and set [`TelemetryFormat.scale`](#com-jprofiler-api-probe-injected-telemetry-telemetryformat-scale) to `-3`.

#### Methods

| Signature | Returns | Description |
|---|---|---|
| [`values()`](#com-jprofiler-api-probe-injected-telemetry-telemetryunit-values) | `TelemetryUnit[]` |  |
| [`valueOf(String)`](#com-jprofiler-api-probe-injected-telemetry-telemetryunit-valueof-string) | `TelemetryUnit` |  |

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-values"></a>##### values()

```java
public static TelemetryUnit[] values()
```

<a id="com-jprofiler-api-probe-injected-telemetry-telemetryunit-valueof-string"></a>##### valueOf(String)

```java
public static TelemetryUnit valueOf(String name)
```