Custom Probes

## Custom Probes |

| For more information on custom probes, please see the corresponding help topic. Here, only the configuration of custom probes in the JProfiler GUI is discussed. If you add or edit a custom probe, the custom probe wizard is displayed. In several steps, it leads you through the creation of a custom probe. You can directly jump to another step of the wizard by clicking on the step in the index. The wizard is partitioned into the following steps: Name and description Here, you provide a name and a description for the probe. The name is used in the call to `ProbeMetaData#create(String)` and the description is set with `ProbeMetaData#description(String)`. This could be set in the meta data script in the next step, but since JProfiler needs to display this information in the custom probe configuration, it is entered separately outside the script and applied to the `ProbeMetaData` object before it is passed to the meta data script. Meta data The meta data of the probe is configured with a single script. The script is passed a single parameter `metaData` of type `ProbeMetaData` and does not return anything. New probes contain a non-functional example script that gives you a starting point for your own configuration. Telemetry script If the probe publishes telemetries, a telemetry script is called once a second and gives you the chance to publish telemetry data. The script is passed a `ProbeContext` and an int-array with the data to be filled. To retrieve data that was collected during interceptions, you have to use the map returned by `probeContext.getMap()`. The n-th index in the int-array corresponds to the n-th telemetry that was defined in the meta-data script. Method groups The interception scripts later on operate on several methods of the same signature. If you have to deal with methods of different signatures (which is common for more complex probes), you have to define different method groups. Each method group can only contain methods with the same signature. In subsequent steps, the method group can be selected from a drop-down list in order to configure different method groups. Specify methods If you want to intercept method to collect data (which most probes do), you can add those methods in this step. Remember that all methods in a single method group must have the same signature. There are several ways to enter new methods: Search in configured classpath A class chooser will be shown that shows all classes in the classpath configured in the application settings. Finally you have to select a method from the selected class. Search in other JAR or class files First, you can select a JAR or class file. If the selection is a JRE file, you then have to select a class in a class chooser. After the selection you will be asked whether to expand the classpath with the current selection. For remote sessions, the classpath is often not configured, so this is a shortcut to make your selection permanent. Finally, you can select a method from the selected class. Search in profiled classes If the session is being profiled, a class chooser is displayed that shows all classes in the profiled JVM. There may be classes in the classpath that have not been loaded. Those classes will not be shown in the class chooser. Finally, you can to select a method from the selected class. Enter manually (advanced) This option displays a dialog that allows you to enter class name, method name and method signature in JNI format. The JNI format of the method signature is explained in the javadoc of `com.jprofiler.api.agent.probe.InterceptionMethod`. The context menu for the list of methods offers the option to edit existing entries. Interception scripts The first two parameters passed to an interception script are the `InterceptorContext` (which is an extension of `ProbeContext`) and the current object `currentObject` (which is `null` for static method interceptions). There are interception scripts for three points in the execution flow: Method entry Called immediately after the intercepted method is entered. In addition to the common parameters, all arguments of the intercepted method are passed to the script. As long as the types of the arguments are in the configured class path of the session, method completion is available in the script dialog. Method exit Called just before the intercepted method is exited via a return call. No method arguments are passed. If creating payload information, use the payload stack methods in the interceptor context to retrieve information from the entry script. Exception exit Called just before the intercepted method is exited after an exception has been thrown. In addition to the common parameters, the Throwable `t` is passed as a parameter. The method exit script will not be called in this case. Interception scripts must be defined separately for each method group.

| Custom probes can be organized into custom probe sets. You can add a saved custom probe set to the current list of custom probes or save the current list of custom probes to a set. This makes it easy to share custom probes between different sessions. To automatically add a set of custom probe to new sessions, configure a saved custom probe set on the session defaults tab of the general settings dialog. To share a set of custom probes with a colleague, or to copy it to another JProfiler installation, use the import/export feature.