This is documentation for the next version of Pyroscope. For the latest stable release, go to the latest version.
Set up Java profiling using Grafana Alloy
Grafana Alloy supports Java profiling. The collector configuration file is composed of components that are used to collect, transform, and send data. The Alloy configuration files use the Alloy configuration syntax.
Configure the components
The pyroscope.java
component is used to continuously profile Java processes running on the local Linux OS
using async-profiler.
pyroscope.java "java" {
profiling_config {
interval = "15s"
alloc = "512k"
cpu = true
lock = "10ms"
sample_rate = 100
}
forward_to = [pyroscope.write.endpoint.receiver]
targets = discovery.relabel.java.output
}
Using the targets
argument, you can specify which processes and containers to profile on the machine.
The targets
can be from discovery.process
component.
You can use discovery.process
join argument to join process targets with extra discoveries such as discovery.kubernetes
, discovery.docker
, and discovery.dockerswarm
.
You can use the discovery.relabel
component to relabel discovered targets and set your own labels.
For more information, refer to the Components documentation.
The forward_to
parameter should point to a pyroscope.write
component to send the collected profiles to your
Pyroscope Server or Grafana Cloud.
The special label __process_pid__
must always be present in each target of targets
and corresponds to the PID
of
the process to profile.
The special label service_name
is required and must always be present.
If service_name
isn’t specified, pyroscope.java
attempts to infer it from discovery meta labels.
If service_name
isn’t specified and couldn’t be inferred, then it’s set to unspecified
.
The profiling_config
block describes how async-profiler is invoked.
It supports the following arguments:
For more information on async-profiler configuration, see profiler-options.
Set privileges for the collector
You must run the collector, such Alloy, as root and inside host pid
namespace for the pyroscope.java
and discover.process
components to work.
Start the collector
To start Grafana Alloy v1.2 and later, replace configuration.alloy
with your configuration filename:
alloy run configuration.alloy
To start Grafana Alloy v1.0 or 1.1, replace configuration.alloy
with your configuration file name:
alloy run --stability.level=public-preview configuration.alloy
The stability.level
option is required for pyroscope.scrape
with Alloy v1.0 or v1.1. For more information about stability.level
, refer to the run command documentation.
Send data to Grafana Cloud Profiles
When sending to Grafana Cloud Profiles, you can use the following pyroscope.write
component configuration which uses environment variables.
Ensure that you have appropriately configured the GC_URL
, GC_USER
, and GC_PASSWORD
environment variables.
pyroscope.write "endpoint" {
endpoint {
basic_auth {
password = env("GC_PASSWORD")
username = env("GC_USER")
}
url = env("GC_URL")
}
}
Examples
For more robust examples, refer to the Grafana Alloy and Agent Auto-instrumentation examples in the Pyroscope repository.
Profiling local process
Profiling Docker containers
For a working example, refer to Java profiling via auto-instrumentation example in Docker.
Profiling Kubernetes pods
For a working example, refer to Grafana Alloy Java profiling via auto-instrumentation with Kubernetes.
References
For more information: