github.com/grafana/pyroscope@v1.18.0/examples/grafana-alloy-auto-instrumentation/java/docker/README.md (about)

     1  # Java profiling via auto-instrumentation example in Docker with Grafana Alloy
     2  
     3  This repository provides a practical demonstration of leveraging the Grafana Alloy for continuous Java application profiling using Pyroscope in a dockerized environment. It illustrates a seamless approach to profiling Java processes, aiding in performance optimization.
     4  
     5  ## Overview
     6  
     7  Grafana Alloy automates Java process discovery for profiling, streamlining the setup per application. It enables precise and targeted profiling configurations through Grafana Alloy settings.
     8  
     9  Java profiling via Grafana Alloy is based on a few Grafana Alloy components:
    10  - `discovery.process` (and optionally `discovery.kubernetes`) for process discovery
    11  - `discovery.relabel` for detecting java processes and setting up labels
    12  - `pyroscope.java` for enabling profiling for specific applications
    13  - `pyroscope.write` for writing the profiles data to a remote endpoint
    14  
    15  Refer to the [official documentation](https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/java/) for an in-depth understanding and additional configuration options for Java profiling with Grafana Alloy.
    16  Also, check the [Grafana Alloy Components reference](https://grafana.com/docs/alloy/latest/reference/components/) for more details on each used component.
    17  
    18  ### async-profiler
    19  
    20  The `pyroscope.java` component internally uses the [async-profiler](https://github.com/async-profiler/async-profiler) library.
    21  This approach offers a key advantage over other instrumentation mechanisms in that you can profile applications that are already running without interruptions (code changes, config changes or restarts).
    22  
    23  Under the hood, this is achieved by attaching to the application at a process level and issuing commands to control profiling.
    24  
    25  ## Getting started
    26  
    27  To use this example:
    28  
    29  1. Install and run Docker.
    30  2. Clone this repository and navigate to the example's directory.
    31  3. Use Docker Compose to build and initiate the container:
    32  
    33  ```shell
    34  # Pull latest pyroscope and grafana images:
    35  docker pull grafana/pyroscope:latest
    36  docker pull grafana/grafana:latest
    37  docker pull grafana/alloy:latest
    38  
    39  docker-compose up --build
    40  ```
    41  
    42  After the container is operational, Grafana Alloy profiles the Java application using he defined configuration.
    43  
    44  ### Observe profiling data
    45  
    46  Now that everything is set up, you can browse profiling data through the [Explore profiles app](http://localhost:3000/a/grafana-pyroscope-app/profiles-explorer).
    47  
    48  ![image](https://github.com/user-attachments/assets/16f5559a-0bbc-4cf3-9589-fa4374bbc7e8)
    49  ![image](https://github.com/user-attachments/assets/ca28d228-93c3-4e16-a63c-285005c7b203)
    50  
    51  
    52  
    53  ## Considerations
    54  
    55  You need root privileges to run Grafana Alloy for profiling. It must be executed within the host's PID namespace.
    56  
    57  ## Documentation
    58  
    59  Refer to the [official documentation](https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/java/) for an in-depth understanding and additional configuration options for Java profiling with Grafana Alloy.