The Java profiling agent for Pyroscope.io. Based on async-profiler.

Distribution

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

Windows OS support

It also contains support for Windows OS, through JFR profiler. In order to use JFR as profiler in place of async-profiler, you need to configure profiler type, either through configuration file or environment variable.

By setting PYROSCOPE_PROFILER_TYPE configuration variable to JFR, agent will use JVM built-in profiler.

Downloads

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

Usage

Visit docs page for usage and configuration documentation.

Experimental OTLP Profiles export

The agent can export async-profiler recordings using the experimental OpenTelemetry Profiles signal. Set PYROSCOPE_FORMAT=otlp and configure PYROSCOPE_SERVER_ADDRESS with the base address of an OTLP/HTTP receiver. The agent sends protobuf requests to <server-address>/v1development/profiles.

OTLP export requires the default ASYNC profiler and is not supported by the JFR profiler used on Windows. Only one profiling event can run at a time. Allocation and lock thresholds can be configured when their event is selected, for example with PYROSCOPE_PROFILER_EVENT=alloc and PYROSCOPE_PROFILER_ALLOC=512k. Multiple events remain supported in sampling mode because they run sequentially. The OpenTelemetry Profiles protocol and async-profiler output are experimental and may change incompatibly.

Building

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.

Maintainers

This package is maintained by @grafana/pyroscope-java. Mention this team on issues or PRs for feedback.