The Java profiling agent for Pyroscope.io. Based on async-profiler.
The agent is distributed as a single JAR file pyroscope.jar
. It contains native async-profiler libraries for:
- Linux on x64;
- Linux on x86;
- Linux on AArch64;
- Linux on ARM;
- MacOS on x64.
Visit releases page to download the latest version of pyroscope.jar
To run a Java application with the agent:
java -javaagent:pyroscope.jar -jar app.jar
On the startup, the agent deploys the native corresponding library into /tmp/${username}-pyroscope/
.
The agent is configured using environment variables.
PYROSCOPE_APPLICATION_NAME
: The application name used when uploading profiling data. Generated if not provided.PYROSCOPE_PROFILING_INTERVAL
: Sets the profiling interval in nanoseconds or in other units, if N is followed byms
(for milliseconds),us
(for microseconds), ors
(for seconds). See async-profiler documentation for details. The default is10ms
.PYROSCOPE_UPLOAD_INTERVAL
: Sets the profiling interval for uploading snapshots. The default is10s
.PYROSCOPE_PROFILER_EVENT
: Sets the profiling event. See async-profiler documentation for details. The supported values arecpu
,alloc
,lock
,wall
, anditimer
. The defaults isitimer
.PYROSCOPE_LOG_LEVEL
: The log level:debug
,info
,warn
,error
. The default isinfo
.PYROSCOPE_SERVER_ADDRESS
: The address of the Pyroscope server. The default ishttp://localhost:4040
.PYROSCOPE_AUTH_TOKEN
: The authorization token used to upload profiling data.
Starting with version v0.5.0 JFR format is (partially) supported to be able to support multiple events (JFR is the only output format that supports multiple events in async-profiler
).
It currently supports the following events:
- jdk.ExecutionSample (supported in
pyroscope-java >= 0.5.0
andpyroscope >= 0.13.0
), used for CPU sampling events (itimer
,cpu
,wall
). - jdk.ObjectAllocationInNewTLAB (supported in
pyroscope-java >= 0.5.0
andpyroscope >= 0.14.0
), used for alloc sampling. - jdk.ObjectAllocationOutsideTLAB (supported in
pyroscope-java >= 0.5.0
andpyroscope >= 0.14.0
), used for alloc sampling.
There are several environment variables that define how multiple event configuration works:
PYROSCOPE_FORMAT
sets the profiler output format. The default iscollapsed
, but in order to support multiple formats it must be set tojfr
.PYROSCOPE_PROFILER_EVENT
sets the profiler event. With JFR format enabled, this event refers to one of the possible CPU profiling events:itimer
,cpu
,wall
. The default isitimer
.PYROSCOPE_PROFILER_ALLOC
sets the allocation threshold to register the events, in bytes (equivalent to--alloc=
inasync-profiler
. The default value is 0, which means that allocation profiling is disabled. Setting it to1
will register all the events.
If you want to build the agent JAR yourself, from this repo run:
./gradlew shadowJar
The file will be in agent/build/libs/pyroscope.jar
.