Java Profiler
Fully featured low overhead profiler for Java EE and Java SE platforms.
.NET Profiler
Easy-to-use performance and memory .NET profiler for Windows, Linux and macOS.
Connection Broker
Secure and easy profiling in cloud, containers and clustered environments.
YouMonitor
Performance monitoring and profiling of Jenkins, Bamboo, TeamCity, Gradle, Maven, Ant and JUnit.
  1. YourKit Java Profiler help
  2. Profiler HTTP API

Profiler HTTP API

Getting started

YourKit profiler agent exposes language neutral HTTP API which allows to control profiling mode, capture snapshots and get JVM telemetry. The HTTP API is a RESTful in terms that agent's responses do not depend on previous request history.

API is based on HTTP requests and JSON responses. All endpoints use POST methods and receive JSON object as a parameter in a request body. The response is always JSON object and has application/json as a Content-Type.

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

You can use any tool of your choice to send HTTP requests, but in the examples below we will use cURL tool. We suppose that profiled application is running on host and profiler agent listens port.

Profiler agent always opens encrypted SSL socket. If you do not provide the SSL certificate, the agent creates self-signed SSL certificate on the fly. To skip certificate validation, please add -k or --insecure to cURL options.

Requests

POST advanceGeneration

Advances object generation number.

Endpoint

https://host:port/yjp/api/v1/advanceGeneration

Parameters

description - Optional description associated with the generation.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/advanceGeneration \
  -d '{"description" : "Hello, world"}'

POST captureHprofSnapshot

Captures snapshot with heap data in HPROF format.

Endpoint

https://host:port/yjp/api/v1/captureHprofSnapshot

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/captureHprofSnapshot

Response example

{
  "path" : "/home/foobar/Snapshots/DemoApp-2021-11-16.hprof"
}

path - Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.

POST captureMemorySnapshot

Captures snapshot with heap data in YourKit format.

Endpoint

https://host:port/yjp/api/v1/captureMemorySnapshot

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/captureMemorySnapshot

Response example

{
  "path" : "/home/foobar/Snapshots/DemoApp-2021-11-16.snapshot"
}

path - Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.

POST capturePerformanceSnapshot

Captures performance snapshot without heap data.

Endpoint

https://host:port/yjp/api/v1/capturePerformanceSnapshot

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/capturePerformanceSnapshot

Response example

{
  "path" : "/home/foobar/Snapshots/DemoApp-2021-11-16.snapshot"
}

path - Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.

POST clearAllocationData

Clears recorded allocations. When allocation recording starts, collected allocation data is cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v1/clearAllocationData

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/clearAllocationData

POST clearCharts

Clears all charts.

Endpoint

https://host:port/yjp/api/v1/clearCharts

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/clearCharts

POST clearCpuData

Clears current results of CPU profiling in any mode, be it sampling, tracing or call counting. When CPU profiling starts, collected CPU profiling data is cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v1/clearCpuData

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/clearCpuData

POST clearEventTables

Clears event table(s) by name. If the specified tables have dependent tables, they will be cleared too.

Endpoint

https://host:port/yjp/api/v1/clearEventTables

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/clearEventTables \
  -d '{"tables" : ["File", "Thread"]}'

POST clearExceptions

Clears recorded exceptions. When exception profiling starts, recorded exceptions are cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v1/clearExceptions

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/clearExceptions

POST clearMonitorData

Clears monitor profiling data. When monitor profiling starts, collected monitor profiling data is cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v1/clearMonitorData

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/clearMonitorData

POST forceGc

Forces garbage collection in the profiled application.

Endpoint

https://host:port/yjp/api/v1/forceGc

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/forceGc

POST getJvmTelemetry

Returns current JVM telemetry.

Endpoint

https://host:port/yjp/api/v1/getJvmTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/getJvmTelemetry

Response example

{
  "totalHeapSize" : 31172040
}

totalHeapSize - Size of JVM heap in bytes.

POST getProbeActivityModes

The mapping of probe class names to the probe activity mode. Mode might be on, off or auto.

Endpoint

https://host:port/yjp/api/v1/getProbeActivityModes

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/getProbeActivityModes

Response example

{
  "com.yourkit.probes.builtin.Sockets" : "auto",
  "com.yourkit.probes.builtin.Sync" : "off",
  "com.yourkit.probes.builtin.Threads" : "on"
}

POST getStatus

Returns the status of the profiler agent. The status describes currently running profiling modes.

Endpoint

https://host:port/yjp/api/v1/getStatus

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/getStatus

Response example

{
  "allocationRecording": true,
  "allocationRecordingSettings": {
    "mode": "exactStacks",
    "recordEach": 10,
    "sizeLimit": 4096,
    "heapSamplingInterval": 0
  },
  "asyncSamplingCpu": false,
  "asyncSamplingPeriodic": false,
  "callCounting": false,
  "cpuProfiling": false,
  "deadlockDetected": false,
  "exceptionProfiling": false,
  "monitorProfiling": false,
  "pid": 37568,
  "sampling": false,
  "appName": "SwingSet2",
  "stackTelemetry": false,
  "tracing": false,
  "agentVersion": "YourKit Java Profiler 2022.3-b55"
}

POST getTotalCreatedObjects

Statistics of object allocation recording.

Endpoint

https://host:port/yjp/api/v1/getTotalCreatedObjects

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/getTotalCreatedObjects

Response example

{
  "count" : 25694429,
  "size" : 1481721664
}

count - Number of created objects.

size - Size in bytes.

POST getTriggers

Obtains current trigger description. If there are no triggers, an empty string will be returned.

Endpoint

https://host:port/yjp/api/v1/getTriggers

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/getTriggers

Response example

{
  "triggers" : ""
}

triggers - The trigger description.

POST setProbeActivityModes

Changes probe activity modes of the specified probes.

Endpoint

https://host:port/yjp/api/v1/setProbeActivityModes

Parameters

Mapping of probe class names to probe activity mode. It specifies the probes whose mode should be changed. If a probe is not present in the mapping, its mode will remain unchanged. Mode might be on, off or auto.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/setProbeActivityModes \
-d '{
  "com.yourkit.probes.builtin.Sockets" : "off",
  "com.yourkit.probes.builtin.Threads" : "on"
}'

POST setTriggers

Sets triggers.

Endpoint

https://host:port/yjp/api/v1/setTriggers

Parameters

triggers - Description of trigger(s).

append - If true, the triggers will be added to the currently existing triggers. If false will be replaced.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/setTriggers \
-d '{
  "triggers" : "TimerListener delay=1h maxTriggerCount=-1\n  PrintMessage message=Hello output=stdout\n",
  "append":false
}'

POST startAllocationRecording

Starts object allocation recording. The method clears previously recorded allocation data.

Endpoint

https://host:port/yjp/api/v1/startAllocationRecording

Parameters

mode - Allocation recording mode. One of counting | exactStacks | sampledStacks | heapSampling

sizeLimit - Applicable in the modes exactStacks and sampledStacks. Record all objects with at least the specified size in bytes. If the parameter is missing, the default size 4096 (4 KB) is applied.

recordEach - Applicable in the modes exactStacks and sampledStacks. Record every N-th object smaller than the sizeLimit. If the parameter is missing, the default value 10 is applied.

heapSamplingInterval - Applicable in the mode heapSampling. Specify the heap sampling interval in bytes. If the parameter is missing, the default value 131072 (128 KB) is applied.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startAllocationRecording \
  -d '{ "mode" : "counting"}'

POST startAsyncSamplingCpu

Starts asynchronous CPU sampling.

Asynchronous sampling is a low overhead profiling mode that does not suffer from Safepoint bias problem. It features HotSpot-specific APIs to collect stack traces. It works with OpenJDK, Oracle JDK and other Java runtimes based on the HotSpot JVM.

Endpoint

https://host:port/yjp/api/v1/startAsyncSamplingCpu

Parameters

settings - CPU sampling settings. Absent parameter means the use of profiled application's settings.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startAsyncSamplingCpu

POST startAsyncSamplingPeriodic

Starts asynchronous periodic sampling.

Asynchronous sampling is a low overhead profiling mode that does not suffer from Safepoint bias problem. It features HotSpot-specific APIs to collect stack traces. It works with OpenJDK, Oracle JDK and other Java runtimes based on the HotSpot JVM.

Endpoint

https://host:port/yjp/api/v1/startAsyncSamplingPeriodic

Parameters

settings - CPU sampling settings. Absent parameter means the use of profiled application's settings.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startAsyncSamplingPeriodic

POST startCallCounting

Starts CPU call counting. Unlike other CPU profiling modes only method invocations are counted, neither call stacks nor times are gathered.

Endpoint

https://host:port/yjp/api/v1/startCallCounting

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startCallCounting

POST startExceptionProfiling

Starts exception profiling. If exception profiling is not running when this method is called, previous exception profiling data is cleared. If exception profiling is already running, this method has no effect.

Endpoint

https://host:port/yjp/api/v1/startExceptionProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startExceptionProfiling

POST startMonitorProfiling

Starts monitor profiling. If monitor profiling is not running when this method is called, previous monitor profiling data is cleared. If monitor profiling is already running, this method has no effect.

Endpoint

https://host:port/yjp/api/v1/startMonitorProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startMonitorProfiling

POST startSampling

Starts CPU sampling. When sampling is used, the profiler periodically queries stacks and times of running threads to estimate the slowest parts of the code. In this mode method invocation counts are not available.

Endpoint

https://host:port/yjp/api/v1/startSampling

Parameters

settings - CPU sampling settings. Absent parameter means the use of profiled application's settings.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startSampling

POST startStackTelemetry

Starts collecting thread stack and state telemetry. If this telemetry is already being collected, the method has no effect.

Endpoint

https://host:port/yjp/api/v1/startStackTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startStackTelemetry

POST startTracing

Starts CPU tracing. When tracing is used, the profiler instruments the bytecode of the profiled application for recording time spent inside each profiled method. Both times and invocation counts are available.

Endpoint

https://host:port/yjp/api/v1/startTracing

Parameters

settings - CPU tracing settings. Absent parameter means the use of profiled application's settings.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/startTracing

POST stopAllocationRecording

Stops allocation recording. If allocation recording is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v1/stopAllocationRecording

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/stopAllocationRecording

POST stopCpuProfiling

Stops CPU profiling in any mode, be it sampling, tracing or call counting. If CPU profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v1/stopCpuProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/stopCpuProfiling

POST stopExceptionProfiling

Stops exception profiling. If exception profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v1/stopExceptionProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/stopExceptionProfiling

POST stopMonitorProfiling

Stops monitor profiling. If monitor profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v1/stopMonitorProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/stopMonitorProfiling

POST stopStackTelemetry

Stops collecting thread stack and state telemetry. If this telemetry is not being collected, the method has no effect.

Endpoint

https://host:port/yjp/api/v1/stopStackTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v1/stopStackTelemetry

YourKit uses cookies and other tracking technologies to improve your browsing experience on our website, to show you personalized content and targeted ads, to analyze our website traffic, and to understand where our visitors are coming from.

By browsing our website, you consent to our use of cookies and other tracking technologies in accordance with the Privacy Policy.