Probe registration, activity modes

To apply a probe, it should be registered.

Built-in probes are pre-compiled and are ready for registration out of the box. If you have written a custom probe, compile it before registering.

There are two ways to register probes:

• On startup (via startup options)
• In runtime (via API)

Probe activity modes

When a probe is registered, its target classes are permanently instrumented with the probe callbacks, which behave depending on the probe activity mode:

• On: the callbacks are active and do their job.

• Off: the callbacks are empty and do nothing. The effect is the same as if the probe was not registered at all. The probe overhead in this mode is almost negligible.

• Auto: the probe is active only while CPU profiling is running: the probe automatically turns On when CPU profiling starts and then automatically turns Off when CPU profiling stops. This mode is intended for the probes whose results are naturally associated with CPU profiling session, and/or would impose undesirable overhead when no profiling is being performed. When CPU profiling results are cleared, either by starting CPU profiling or explicitly, the tables of the Auto probes are automatically cleared too.

Initial activity mode is controlled via corresponding startup options (see below).

Obtaining and changing activity mode in runtime

• Using the profiler UI: when the profiler is connected to a profiled application, switch to the "Events" tab and press the "Manage Probes" button.
• Using API: use methods getProbeActivityModes() and setProbeActivityModes() of com.yourkit.api.controller.Controller

Default activity modes

Probes	Default mode
JSP/Servlets, databases, files, directory streams, sockets	Auto
Class loading, threads, processes, AWT events	On
JUnit and TestNG tests	On (*)
user-defined probes	n/a (On or Auto explicitly specified)

(*) Only if the agent loads on start. In attach mode the probe is by default disabled.

Probe registration on startup

Register probes on startup to apply them without altering the profiled application source code. This is especially important for applications such as Java servers, and/or production versions of the software.

Also, registration on startup is the simplest way to apply probes.

The following startup options control the initial mode. They work for both built-in and user-defined probes.

Startup option	Description
probe_on=<full qualified probe class name or pattern> probe_off=<full qualified probe class name or pattern> probe_auto=<full qualified probe class name or pattern>	Until any of the probe_* options is processed, or if none of them is specified, the list of probes to be registered on startup consists of the built-in probes in their default mode, either On or Auto (see table). The options set the initial mode of matching probes to On, Off, Auto. If the specified full qualified name is a pattern, i.e. contains * as a wildcard, the mode of all matching probes to be registered will be changed to the specified mode. If a full qualified name without the wildcard is specified, the probe will be added to the list of probes to be registered, and its initial mode will be as the option specifies. You can later change the mode of these probes in runtime by using the UI or the API. Note: the order of probe_* options matter: they are applied from left to right, and further options can override the previous ones.
probe_disable=<full qualified probe class name or pattern>	Until any of the probe_* options is processed, or if none of them is specified, the list of probes to be registered on startup consists of the built-in probes in their default mode, either On or Auto (see table). probe_disable removes matching probes from the list of probes to be registered on startup. This totally eliminates the matching probes: no classes will be instrumented with their callbacks. You won't be able to change the probe mode in runtime by using the UI. Although you will be able to use the API to register the probe in runtime, it's instead recommended to use the option probe_off and activate the probe on demand by changing its mode to On or Auto. Note: the order of probe_* options matter: they are applied from left to right, and further options can override the previous ones.

To specify where a custom probe class should be loaded from, use the following options:

Startup option	Description
probeclasspath=<classpath>	Add the list of jar files and/or directories to system class path to search probe classes in. If several path elements are specified they should be separated with the system-specific path separator which is ';' on Windows and ':' on other platforms. There is no need to specify the path for built-in probes. Note: this option alone does not automatically register any probe classes, it just defines where they are located. You must explicitly specify which probe classes to register by using the options probe_on, probe_off or probe_auto.
probebootclasspath=<classpath>	Add the list of jar files and/or directories to boot class path to probe classes in. If several path elements are specified they should be separated with the system-specific path separator which is ';' on Windows and ':' on other platforms. There is no need to specify the path for built-in probes. Note: this option alone does not automatically register any probe classes, it just defines where they are located. You must explicitly specify which probe classes to register by using the options probe_on, probe_off or probe_auto.

Examples

1. probe_on=*

All (built-in) probes are On. This was the default behavior in the previous versions.

2. probe_off=com.yourkit.probes.builtin.Databases

A short form is available for built-in probes: use a dot instead of the package name probe_off=.Databases

Databases probe will be Off. Other probes will be in their default mode.

3. probe_disable=*,probe_on=com.foo.Bar

Disable all built-in probes and register a user-defined probe class com.foo.Bar, whose initial mode is On.

4. probe_auto=com.foo.Bar

Register a user-defined probe class com.foo.Bar, whose initial mode is Auto. The built-in probes will be in their default mode.

Probe registration in runtime

Use API to register probes programmatically in runtime.

To register the probe, invoke static method registerProbes() of class com.yourkit.probes.Probes:

// register probe classes
public static void registerProbes(Class... probeClasses);

// register probe classes by class name
public static void registerProbes(String... probeClassNames);

When probes are registered by name using registerProbes(String...), the probe classes will be searched in paths specified with the help of startup options probeclasspath=<classpath> and probebootclasspath=<classpath> (see above). There is no need to specify the paths for built-in probes.

Using registerProbes(Class...) you already supply loaded probe classes, thus no search in paths is performed.

Example:

import com.yourkit.probes.*;
// ...
Probes.registerProbes(MyProbe.class);
Probes.registerProbes("com.foo.Probe1", "com.foo.Probe2");