Profiler HTTP API

Getting started

YourKit profiler agent exposes language neutral HTTP API which allows to control profiling and capture snapshots. 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` captureMemorySnapshot

Captures snapshot with heap data.

Endpoint

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

Parameters

No.

cURL example

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

Response example

{
  "path" : "/home/foobar/Snapshots/Demo.dll.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 snapshot without heap data.

Endpoint

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

Parameters

No.

cURL example

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

Response example

{
  "path" : "/home/foobar/Snapshots/Demo.dll.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 object 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/ynp/api/v1/clearAllocationData

Parameters

No.

cURL example

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

`POST` clearCharts

Clears all charts.

Endpoint

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

Parameters

No.

cURL example

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

`POST` clearCpuData

Clears current results of CPU profiling in any mode, be it sampling or tracing. 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/ynp/api/v1/clearCpuData

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/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/ynp/api/v1/clearEventTables

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v1/clearEventTables \
  -d '{"tables" : ["Class Loading", "Message"]}'

`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/ynp/api/v1/clearExceptions

Parameters

No.

cURL example

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

`POST` forceGc

Forces garbage collection in the profiled application.

Endpoint

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

Parameters

No.

cURL example

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

`POST` getProbeActivityModes

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

Endpoint

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

Parameters

No.

cURL example

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

Response example

{
  "YourKit.Probes.ClassLoading" : "on",
  "YourKit.Probes.Databases" : "auto",
  "YourKit.Probes.Files" : "off"
}

`POST` getStatus

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

Endpoint

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

Parameters

No.

cURL example

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

Response example

{
  "allocationRecording" : true,
  "allocationRecordingSettings" : {
    "mode" : "exactStacks",
    "recordEach" : 10,
    "sizeLimit" : 4096
  },
  "cpuProfiling" : false,
  "exceptionProfiling" : true,
  "pid" : 42069,
  "sampling" : false,
  "sessionName" : "Demo.dll",
  "stackTelemetry" : true,
  "tracing" : false,
  "agentVersion" : "YourKit .NET Profiler 2022.3-b55"
}

`POST` getTotalCreatedObjects

Statistics of object allocation recording.

Endpoint

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

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/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/ynp/api/v1/getTriggers

Parameters

No.

cURL example

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

Response example

{
  "triggers" : "TimerListener maxTriggerCount=-1 delay=5m\n  ForceGc\n"
}

triggers - The trigger description.

`POST` setProbeActivityModes

Changes probe activity modes of the specified probes.

Endpoint

https://host:port/ynp/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/ynp/api/v1/setProbeActivityModes \
-d '{
  "YourKit.Probes.ClassLoading" : "off",
  "YourKit.Probes.Databases" : "on"
}'

`POST` setTriggers

Sets triggers.

Endpoint

https://host:port/ynp/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/ynp/api/v1/setTriggers \
-d '{
  "triggers" : "TimerListener maxTriggerCount=-1 delay=5m\n  ForceGc\n",
  "append" : false
}'

`POST` startAllocationRecording

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

Endpoint

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

Parameters

sizeLimit - Minimum size in bytes of object to record. Absent parameters means default size.

recordEach - Record every N-th object. Absent parameters means default value.

cURL example

curl -k -X POST https://host:port/ynp/api/v1/startAllocationRecording \
-d '{
  "sizeLimit" : 128,
  "recordEach" : 10
}'

`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/ynp/api/v1/startExceptionProfiling

Parameters

No.

cURL example

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

`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/ynp/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/ynp/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/ynp/api/v1/startStackTelemetry

Parameters

No.

cURL example

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

`POST` startTracing

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

Endpoint

https://host:port/ynp/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/ynp/api/v1/startTracing

`POST` stopAllocationRecording

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

Endpoint

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

Parameters

No.

cURL example

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

`POST` stopCpuProfiling

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

Endpoint

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

Parameters

No.

cURL example

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

`POST` stopExceptionProfiling

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

Endpoint

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

Parameters

No.

cURL example

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

`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/ynp/api/v1/stopStackTelemetry

Parameters

No.

cURL example

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

Profiler HTTP API

Getting started

Requests

POST captureMemorySnapshot

Endpoint

Parameters

cURL example

Response example

POST capturePerformanceSnapshot

Endpoint

Parameters

cURL example

Response example

POST clearAllocationData

Endpoint

Parameters

cURL example

POST clearCharts

Endpoint

Parameters

cURL example

POST clearCpuData

Endpoint

Parameters

cURL example

POST clearEventTables

Endpoint

Parameters

cURL example

POST clearExceptions

Endpoint

Parameters

cURL example

POST forceGc

Endpoint

Parameters

cURL example

POST getProbeActivityModes

Endpoint

Parameters

cURL example

Response example

POST getStatus

Endpoint

Parameters

cURL example

Response example

POST getTotalCreatedObjects

Endpoint

Parameters

cURL example

Response example

POST getTriggers

Endpoint

Parameters

cURL example

Response example

POST setProbeActivityModes

Endpoint

Parameters

cURL example

POST setTriggers

Endpoint

Parameters

cURL example

POST startAllocationRecording

Endpoint

Parameters

cURL example

POST startExceptionProfiling

Endpoint

Parameters

cURL example

POST startSampling

Endpoint

Parameters

cURL example

POST startStackTelemetry

Endpoint

Parameters

`POST` captureMemorySnapshot

`POST` capturePerformanceSnapshot

`POST` clearAllocationData

`POST` clearCharts

`POST` clearCpuData

`POST` clearEventTables

`POST` clearExceptions

`POST` forceGc

`POST` getProbeActivityModes

`POST` getStatus

`POST` getTotalCreatedObjects

`POST` getTriggers

`POST` setProbeActivityModes

`POST` setTriggers

`POST` startAllocationRecording

`POST` startExceptionProfiling

`POST` startSampling

`POST` startStackTelemetry

`POST` startTracing

`POST` stopAllocationRecording

`POST` stopCpuProfiling

`POST` stopExceptionProfiling

`POST` stopStackTelemetry