Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana Pyroscope Configure the Client Language SDKs Java

Java

How to add Java profiling to your application

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 applications

You can start Pyroscope either from your apps’s Java code or attach it as javaagent.

Start Pyroscope from app’s Java code

First, add Pyroscope dependency

Maven

xml Copy

<dependency>
  <groupId>io.pyroscope</groupId>
  <artifactId>agent</artifactId>
  <version>pyroscope_version</version>
</dependency>

Gradle

shell Copy

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

Then add the following code to your application:

java Copy

PyroscopeAgent.start(
  new Config.Builder()
    .setApplicationName("ride-sharing-app-java")
    .setProfilingEvent(EventType.ITIMER)
    .setFormat(Format.JFR)
    .setServerAddress("http://pyroscope-server:4040")
    .build()
);

You can also optionally replace some Pyroscope components:

java Copy

PyroscopeAgent.start(
  new PyroscopeAgent.Options.Builder(config)
    .setExporter(snapshot -> {
      // Your custom export/upload logic may go here
      // It is invoked every 10 seconds by default with snapshot of
      // profiling data
    })
    .setLogger((l, msg, args) -> {
      // Your custom logging may go here
      // Pyroscope does not depend on any logging library
      System.out.printf((msg) + "%n", args);
    })
    .setScheduler(profiler -> {
      // Your custom profiling schedule logic may go here
    })
    .build()
);

Start Pyroscope as javaagent

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

shell Copy

export PYROSCOPE_APPLICATION_NAME=my.java.app
export PYROSCOPE_SERVER_ADDRESS=http://pyroscope-server:4040

java -javaagent:pyroscope.jar -jar app.jar

How to add profiling labels to Java applications

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 labels dynamically:

java Copy

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

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

java Copy

Pyroscope.setStaticLabels(Map.of("region", System.getenv("REGION")));
// or with Config.Builder if you start pyroscope with PyroscopeAgent.start
PyroscopeAgent.start(new Config.Builder()
    .setLabels(mapOf("region", System.getenv("REGION")))
    // ...
    .build()
);

Java client configuration options

When you start Pyroscope as javaagent or obtain configuration by Config.build() Pyroscope searches for configuration in multiple sources: system properties, environment variables, and pyroscope.properties. Property keys have same name as environment variables, but are lowercased and replace _ with .. For example, PYROSCOPE_FORMAT becomes pyroscope.format

The 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:

Sending data to Pyroscope OSS or Grafana Cloud Profiles with Pyroscope java SDK

Add the following code to your application:

java Copy

PyroscopeAgent.start(
    new Config.Builder()
        .setApplicationName("test-java-app")
        .setProfilingEvent(EventType.ITIMER)
        .setFormat(Format.JFR)
        .setServerAddress("<URL>")
        .setBasicAuthUser("<User>")
        .setBasicAuthPassword("<Password>")
        // Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana cloud.
        // .setTenantID("<TenantID>")
        .build()
);

To configure the Java SDK to send data to Pyroscope, replace the <URL> placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.

If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User> with your Grafana Cloud stack user and <Password> with your Grafana Cloud API key.

If your Pyroscope server has multi-tenancy enabled, you’ll need to configure a tenant ID. Replace <TenantID> with your Pyroscope tenant ID.

Java profiling examples

Check out the following resources to learn more about Java profiling:

• Java examples
• Java Demo showing Java example with tags
• Java blog post