Skip to main content

Java

Pyroscope uses async-profiler to collect profiling data from Java applications.

Supported platforms#

LinuxmacOSWindowsDocker
โœ…โœ…โœ…

Installation#

Java integration is distributed as a single jar file: pyroscope.jar. It contains native async-profiler libraries for:

  • Linux on x64;
  • Linux on ARM64;
  • MacOS on x64.
  • MacOS on ARM64.

Visit our GitHub releases page to download the latest version of pyroscope.jar.

The latest release is also available on Maven Central.

Profiling Java application#

To start profiling a Java application, run your application with pyroscope.jar javaagent:

export PYROSCOPE_APPLICATION_NAME=my.java.appexport PYROSCOPE_SERVER_ADDRESS=http://pyroscope-server:4040
# Optionally, if authentication is enabled, specify the API key.# export PYROSCOPE_AUTH_TOKEN={YOUR_API_KEY}
java -javaagent:pyroscope.jar -jar app.jar

Starting with v0.5.0, Java integration supports JFR format to be able to support multiple events (JFR is the only output format that supports multiple events in async-profiler). There are several environment variables that define how multiple event configuration works:

  • PYROSCOPE_FORMAT sets the profiler output format. The default is collapsed, but in order to support multiple formats it must be set to jfr.
  • 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 is itimer.
  • PYROSCOPE_PROFILER_ALLOC sets the allocation threshold to register the events, in bytes (equivalent to --alloc= in async-profiler). The default value is "" - empty string, which means that allocation profiling is disabled. Setting it to 0 will register all the events.
  • PYROSCOPE_PROFILER_LOCK sets the lock threshold to register the events, in nanoseconds (equivalent to --lock= in async-profiler). The default value is "" - empty string, which means that lock profiling is disabled. Setting it to 0 will register all the events.

Labels#

It is possible to add dynamic tags (labels) to the profiling data. These tags can be used to filter the data in the UI.

Add pyroscope dependency to your build.gradle:

implementation("io.pyroscope:agent:${pyroscope_version}")

Add labels dynamically:

import io.pyroscope.labels.LabelsSet;import io.pyroscope.labels.Pyroscope;
Pyroscope.LabelsWrapper.run(new LabelsSet("controller", "slow_controller"), () -> {    slowCode();});

It is also possible to possible to add static tags (labels) to the profiling data:

import io.pyroscope.labels.Pyroscope;
Pyroscope.setStaticLabels(Map.of("REGION", System.getenv("REGION")));

Examples#

Check out the examples folder in our repository to learn more ๐Ÿ”ฅ