Documentation Grafana Alloy Reference Components pyroscope pyroscope.java

pyroscope.java

pyroscope.java continuously profiles Java processes running on the local Linux OS using async-profiler.

You can specify multiple pyroscope.java components by giving them different labels.

Usage

Alloy Copy

pyroscope.java "<LABEL>" {
  targets    = <TARGET_LIST>
  forward_to = <RECEIVER_LIST>
}

Target JVM configuration

When you use pyroscope.java to profile Java applications, you can configure the target JVMs with some command line flags that ensure accurate profiling, especially for inlined methods. Add the following flags to your Java application’s startup command:

java Copy

-XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints

For more details, refer to Restrictions/Limitations in the async-profiler documentation.

Additional configuration for Linux capabilities

If your Kubernetes environment has Linux capabilities enabled, configure the following in your Helm values to ensure pyroscope.java functions properly:

YAML Copy

alloy:
  securityContext:
    runAsUser: 0
    runAsNonRoot: false
    capabilities:
      add:
        - PERFMON
        - SYS_PTRACE
        - SYS_RESOURCE
        - SYS_ADMIN

These capabilities enable Alloy to access performance monitoring subsystems, trace processes, override resource limits, and perform necessary system administration tasks for profiling.

Arguments

You can use the following arguments with pyroscope.java:

After component startup, pyroscope.java creates a temporary directory under the tmp_dir argument and extracts the async-profiler binaries for both glibc and musl into the directory with the following layout.

text Copy

/tmp/alloy-asprof-glibc-{SHA1}/bin/asprof
/tmp/alloy-asprof-glibc-{SHA1}/lib/libasyncProfiler.so
/tmp/alloy-asprof-musl-{SHA1}/bin/asprof
/tmp/alloy-asprof-musl-{SHA1}/lib/libasyncProfiler.so

After process profiling startup, the component detects libc type and copies the matching libasyncProfiler.so into the target process’s file system at the exact same path.

Each target in the targets argument must always include the special __process_pid__ label, which corresponds to the process PID that’s used for profiling.

The component treats labels that start with a double underscore as internal and removes them before scraping.

Every profile carries a service_name label. You can set it on the target yourself. If you don’t, pyroscope.java adds the label and infers a value from the following sources, in this order:

1. __meta_kubernetes_pod_annotation_pyroscope_io_service_name which is a pyroscope.io/service_name Pod annotation.
2. __meta_kubernetes_namespace and __meta_kubernetes_pod_container_name, combined into java/<namespace>/<container_name>.
3. __meta_docker_container_name
4. __meta_dockerswarm_container_label_service_name or __meta_dockerswarm_service_name

When you don’t set service_name and the component can’t infer a value, it uses unspecified.

Injected labels

Independently of the targets argument, pyroscope.java automatically injects the following labels into collected profiles if you haven’t already defined them:

Alloy only sets otel.scope.name and otel.scope.version if they aren’t already present on the profile. otel.scope.version is only set when otel.scope.name matches the default value.

Blocks

You can use the following block with pyroscope.java:

profiling_config

The profiling_config block describes how the component invokes async-profiler.

You can use the following arguments with the profiling_config block:

Refer to profiler-options for more information about async-profiler configuration.

custom_arguments

custom_arguments passes async-profiler start flags directly.

When you set custom_arguments, Alloy skips these options from this block:

cpu, event, per_thread, sample_rate, alloc, lock, log_level, tlab.

For example, this configuration enables multi-event profiling for cpu, alloc, and lock with custom thresholds:

Alloy Copy

pyroscope.java "java" {
  targets    = discovery.relabel.java.output
  forward_to = [pyroscope.write.staging.receiver]

  profiling_config {
    interval = "60s"
    custom_arguments = ["-e", "cpu,alloc,lock", "--alloc", "2m", "--lock", "10ms"]
  }
}

Refer to Profiling modes and profiler-options for the complete async-profiler option list.

event

The event argument configures the profiling mode used by async-profiler. async-profiler supports various profiling modes including CPU profiling, wall-clock profiling, and hardware performance monitoring events. For a complete overview of all available profiling modes and their use cases, refer to Profiling modes in the async-profiler documentation.

per_thread

Exported fields

pyroscope.java doesn’t export any fields.

Component health

pyroscope.java is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

pyroscope.java doesn’t expose any component-specific debug information.

Debug metrics

pyroscope.java doesn’t expose any component-specific debug metrics.

Example

The following example profiles every Java process on the current host:

Alloy Copy

pyroscope.write "staging" {
  endpoint {
    url = "http://localhost:4040"
  }
}

discovery.process "all" {
  refresh_interval = "60s"
  discover_config {
    cwd = true
    exe = true
    commandline = true
    username = true
    uid = true
    container_id = true
  }
}

discovery.relabel "java" {
  targets = discovery.process.all.targets
  rule {
    action = "keep"
    regex = ".*/java$"
    source_labels = ["__meta_process_exe"]
  }
}

pyroscope.java "java" {
  targets = discovery.relabel.java.output
  forward_to = [pyroscope.write.staging.receiver]
  profiling_config {
    interval = "60s"
    alloc = "512k"
    cpu = true
    sample_rate = 100
    lock = "1ms"
  }
}

Compatible components

pyroscope.java can accept arguments from the following components:

• Components that export Targets
• Components that export Pyroscope ProfilesReceiver