Profiler HTTP API

The YourKit profiler agent provides a language-neutral HTTP API for controlling profiling and capturing snapshots. The API is RESTful in the sense that the agent's responses do not depend on the history of previous requests.

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 agent error.

You can use any tool to send HTTP requests, but in the examples below we will use the cURL command-line tool. We assume that the profiled application is running on a host and that the profiler agent is listening on a port. For details on configuring the port and SSL parameters, see the list of agent options.

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

Requests

captureMemorySnapshot
capturePerformanceSnapshot
clearEventTables
forceGc
getProbeActivityModes
getStatus
getTotalCreatedObjects
getTriggers
resetAllocationProfiling
resetCpuProfiling
resetExceptionProfiling
resetTelemetry
resetThreadProfiling
setProbeActivityModes
setTriggers
startAllocationProfiling
startExceptionProfiling
startSampling
startTelemetry
startThreadProfiling
startTracing
stopAllocationProfiling
stopCpuProfiling
stopExceptionProfiling
stopTelemetry
stopThreadProfiling

`POST` captureMemorySnapshot

Captures snapshot with heap data.

Endpoint

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

Parameters

No.

cURL example

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

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/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` resetAllocationProfiling

Clears recorded allocations. When object allocation profiling 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/v2/resetAllocationProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/resetAllocationProfiling

`POST` resetCpuProfiling

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/v2/resetCpuProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/resetCpuProfiling

`POST` resetTelemetry

Clears all charts.

Endpoint

https://host:port/ynp/api/v2/resetTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/resetTelemetry

`POST` resetThreadProfiling

Clears the collected thread profiling data and continues the thread profiling if it is active.

Endpoint

https://host:port/ynp/api/v2/resetThreadProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/resetThreadProfiling

`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/v2/clearEventTables

Parameters

No.

cURL example

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

`POST` resetExceptionProfiling

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/v2/resetExceptionProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/resetExceptionProfiling

`POST` forceGc

Forces garbage collection in the profiled application.

Endpoint

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

Parameters

No.

cURL example

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

Parameters

No.

cURL example

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

Parameters

No.

cURL example

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

Response example

{
  "allocationProfiling" : true,
  "allocationProfilingSettings" : {
    "interval": 1024
  },
  "cpuProfiling" : false,
  "exceptionProfiling" : true,
  "pid" : 42069,
  "sampling" : false,
  "appName" : "Demo",
  "telemetry" : true,
  "threadProfiling" : true,
  "tracing" : false,
  "agentVersion" : "YourKit .NET Profiler 2024.9-b1"
}

`POST` getTotalCreatedObjects

Statistics of object allocation profiling.

Endpoint

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

Parameters

No.

cURL example

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

Parameters

No.

cURL example

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

`POST` setTriggers

Sets triggers.

Endpoint

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

`POST` startAllocationProfiling

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

Endpoint

https://host:port/ynp/api/v2/startAllocationProfiling

Parameters

interval - Optional allocation interval in bytes. When the total bytes allocated by a .NET thread exceed the specified interval, the profiler records the allocation details.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/startAllocationProfiling \
-d '{
  "interval" : 1024
}'

`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/v2/startExceptionProfiling

Parameters

No.

cURL example

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

`POST` startTelemetry

Starts telemetry collection. If a telemetry collection is already in progress, the method has no effect.

Endpoint

https://host:port/ynp/api/v2/startTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/startTelemetry

`POST` startThreadProfiling

Starts thread profiling. If thread profiling is already in progress, the method has no effect.

Endpoint

https://host:port/ynp/api/v2/startThreadProfiling

Parameters

mode - Thread profiling mode. One of full | states.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/startThreadProfiling \
-d '{ "mode" : "full"}'

`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/v2/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/v2/startTracing

`POST` stopAllocationProfiling

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

Endpoint

https://host:port/ynp/api/v2/stopAllocationProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/stopAllocationProfiling

`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/v2/stopCpuProfiling

Parameters

No.

cURL example

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

`POST` stopExceptionProfiling

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

Endpoint

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

Parameters

No.

cURL example

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

`POST` stopTelemetry

Stops telemetry collection. If a telemetry collection is already stopped, the method has no effect.

Endpoint

https://host:port/ynp/api/v2/stopTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/stopTelemetry

`POST` stopThreadProfiling

Stops thread profiling. If thread profiling is off, the method has no effect.

Endpoint

https://host:port/ynp/api/v2/stopThreadProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/ynp/api/v2/stopThreadProfiling

Profiler HTTP API

Requests

POST captureMemorySnapshot

Endpoint

Parameters

cURL example

Response example

POST capturePerformanceSnapshot

Endpoint

Parameters

cURL example

Response example

POST resetAllocationProfiling

Endpoint

Parameters

cURL example

POST resetCpuProfiling

Endpoint

Parameters

cURL example

POST resetTelemetry

Endpoint

Parameters

cURL example

POST resetThreadProfiling

Endpoint

Parameters

cURL example

POST clearEventTables

Endpoint

Parameters

cURL example

POST resetExceptionProfiling

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 startAllocationProfiling

Endpoint

Parameters

cURL example

POST startExceptionProfiling

Endpoint

Parameters

cURL example

POST startSampling

Endpoint

Parameters

cURL example

`POST` captureMemorySnapshot

`POST` capturePerformanceSnapshot

`POST` resetAllocationProfiling

`POST` resetCpuProfiling

`POST` resetTelemetry

`POST` resetThreadProfiling

`POST` clearEventTables

`POST` resetExceptionProfiling

`POST` forceGc

`POST` getProbeActivityModes

`POST` getStatus

`POST` getTotalCreatedObjects

`POST` getTriggers

`POST` setProbeActivityModes

`POST` setTriggers

`POST` startAllocationProfiling

`POST` startExceptionProfiling

`POST` startSampling

`POST` startTelemetry

`POST` startThreadProfiling

`POST` startTracing

`POST` stopAllocationProfiling

`POST` stopCpuProfiling

`POST` stopExceptionProfiling

`POST` stopTelemetry

`POST` stopThreadProfiling