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

     1  # Grafana Alloy Java profiling via auto-instrumentation in Kubernetes
     2  
     3  This repository provides a practical demonstration of leveraging Grafana Alloy for continuous Java application profiling using Pyroscope in Kubernetes. 
     4  It illustrates a seamless approach to profiling Java processes, aiding in performance optimization.
     5  
     6  ## Overview
     7  
     8  Grafana Alloy automates Java process discovery for profiling, streamlining the setup for applications. It enables precise and targeted profiling configurations through the Grafana Alloy settings.
     9  
    10  Java profiling via Grafana Alloy is based on a few components:
    11  - `discovery.process` for process discovery
    12  - `discovery.kubernetes` for adding Kubernetes labels (namespace, pod, and more)
    13  - `discovery.relabel` for detecting java processes and setting up labels
    14  - `pyroscope.java` for enabling profiling for specific applications
    15  - `pyroscope.write` for writing the profiles data to a remote endpoint
    16  
    17  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.
    18  Also, check the [Grafana Alloy Components reference](https://grafana.com/docs/alloy/latest/reference/components/) for more details on each used component.
    19  
    20  ### async-profiler
    21  
    22  The `pyroscope.java` component internally uses the [async-profiler](https://github.com/async-profiler/async-profiler) library.
    23  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).
    24  
    25  Under the hood, this is achieved by attaching to the application at a process level and issuing commands to control profiling.
    26  
    27  ## Getting started
    28  
    29  To use this example:
    30  
    31  1. Set up a local kubernetes cluster using Kind or a similar tool.
    32  2. Clone this repository and navigate to this example's directory.
    33  3. Create a `pyroscope-java` namespace:
    34      ```shell
    35          kubectl create namespace pyroscope-java
    36      ```
    37  4. Deploy the manifests:
    38      ```shell
    39         kubectl apply -n pyroscope-java -f .
    40      ```
    41  
    42  After the deployment is operational, the Grafana Alloy will profile the Java application using the defined configuration.
    43  The example will deploy a Grafana instance in the same cluster, available via the `grafana` service at port 3000.
    44  
    45  ### Observe profiling data
    46  
    47  You can open grafana in your browser by port-forwarding traffic to the service:
    48  ```shell
    49  kubectl port-forward -n pyroscope-java deployment/grafana 3000 3000
    50  ```
    51  
    52  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).
    53  
    54  ![image](https://github.com/user-attachments/assets/16f5559a-0bbc-4cf3-9589-fa4374bbc7e8)
    55  ![image](https://github.com/user-attachments/assets/ca28d228-93c3-4e16-a63c-285005c7b203)
    56  
    57  
    58  ## Documentation
    59  
    60  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.