grafana · knylander-grafana · May 16, 2024 · May 16, 2024
@@ -1,13 +1,23 @@
 ---
-title: "Grafana Agent"
-menuTitle: "Grafana Agent"
-description: "Send data from your application via the Grafana Agent"
+title: "Grafana Alloy and Grafana Agent"
+menuTitle: "Grafana Alloy and Grafana Agent"
+description: "Send data from your application via using Grafana Alloy or Grafana Agent."
 weight: 10
 aliases:
   - /docs/phlare/latest/configure-client/grafana-agent/
 ---
 
-# Grafana Agent
+# Grafana Alloy and Grafana Agent
+
+You can send data from your application using Grafana Alloy or Grafana Agent collectors.
+Both collectors support profiling with eBPF, Java, and Golang in pull mode.
+
+[Grafana Alloy](https://grafana.com/docs/alloy/latest/) is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector.
+Alloy uniquely combines the very best OSS observability signals in the community.
+Grafana Alloy uses configuration file written using River.
+
+Alloy is the recommended collector instead of Grafana Agent.
+New installations should use Alloy.
 
 {{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
 
@@ -19,8 +29,7 @@ This document provides an overview of these two modes of profiling and guides us
 Refer to [Available profiling types]({{< relref "../../view-and-analyze-profile-data/profiling-types#available-profiling-types" >}}) for a list of profile types supported.
 {{< /admonition >}}
 
-
-## eBPF profiling with Grafana Agent
+## eBPF profiling
 
 eBPF (Extended Berkeley Packet Filter) is a modern Linux kernel technology that allows for safe, efficient, and customizable tracing of system and application behaviors without modifying the source code or restarting processes.
 
@@ -30,16 +39,16 @@ Benefits of eBPF profiling:
 - Versatile: eBPF can trace system calls, network packets, and even user-space application logic.
 - Dynamic: No need to recompile or restart applications. eBPF allows for live tracing.
 
-### Set up eBPF profiling with Grafana Agent
+### Set up eBPF profiling
 
 1. Ensure your system runs a Linux kernel version 4.9 or newer.
-1. Install Grafana Agent on the target machine or container.
+1. Install a collector, such as Grafana Alloy (preferred) or Grafana Agent (legacy), on the target machine or container.
 1. Configure the Agent to use eBPF for profiling. Refer to the [eBPF documentation](/docs/pyroscope/latest/configure-client/grafana-agent/ebpf) for detailed steps.
-1. The Agent collects eBPF profiles and sends them to the Pyroscope server.
+1. The collector collects eBPF profiles and sends them to the Pyroscope server.
 
-## Golang profiling in pull mode with Grafana Agent
+## Golang profiling in pull mode
 
-In pull mode, Grafana Agent periodically retrieves profiles from Golang applications, specifically targeting the pprof endpoints.
+In pull mode, the collector periodically retrieves profiles from Golang applications, specifically targeting the pprof endpoints.
 
 ### Benefits of Golang profiling in pull mode
 
@@ -50,11 +59,11 @@ In pull mode, Grafana Agent periodically retrieves profiles from Golang applicat
 ### Set up Golang profiling in pull mode
 
 1. Ensure your Golang application exposes pprof endpoints.
-1. Install and configure the Grafana Agent on the same machine or container where your application runs.
-1. Ensure the Agent is set to pull mode and targeting the correct pprof endpoints. For step-by-step instructions, visit the [Go (Pull Mode)](/docs/pyroscope/latest/configure-client/grafana-agent/go_pull) docs.
-1. The Agent queries the pprof endpoints of your Golang application, collects the profiles, and forwards them to the Pyroscope server.
+1. Install and configure the collector, either Alloy or Agent, on the same machine or container where your application runs.
+1. Ensure the collector is set to pull mode and targeting the correct pprof endpoints. For step-by-step instructions, visit the [Go (Pull Mode)](/docs/pyroscope/latest/configure-client/grafana-agent/go_pull) documentation.
+1. The collector queries the pprof endpoints of your Golang application, collects the profiles, and forwards them to the Pyroscope server.
 
 ## Next steps
 
-Whether using eBPF for versatile system and application profiling or relying on Golang's built-in pprof endpoints in pull mode, Grafana Agent and Grafana Alloy offer streamlined processes to gather essential profiling data.
+Whether using eBPF for versatile system and application profiling or relying on Golang's built-in pprof endpoints in pull mode, Grafana Agent and Grafana Alloy collectors offer streamlined processes to gather essential profiling data.
 Choose the method that best fits your application and infrastructure needs.
@@ -7,16 +7,15 @@ weight: 10
 
 # Set up Go profiling in pull mode
 
-In pull mode, the Grafana Agent periodically retrieves profiles from Golang applications, specifically targeting the
+In pull mode, the collector, whether Grafana Alloy (preferred) or Grafana Agent (legacy), periodically retrieves profiles from Golang applications, specifically targeting the
 `/debug/pprof/*` endpoints.
 
-
 To set up Golang profiling in pull mode, you need to:
 
 1. Expose pprof endpoints
-2. Install Grafana Agent
-3. Prepare Grafana Agent configuration file
-4. Start Grafana Agent
+2. Install a collector, either Grafana Alloy (preferred) or Grafana Agent (legacy)
+3. Prepare the collector's configuration file
+4. Start the collector
 
 ### Expose pprof endpoints
 
@@ -35,16 +34,25 @@ Ensure your Golang application exposes pprof endpoints.
     import _ "github.com/grafana/pyroscope-go/godeltaprof/http/pprof"
     ```
 
-### Install Grafana Agent
+### Install the collector
 
 [//]: # (TODO&#40;korniltsev&#41; What should go here?)
 
-This procedure uses Grafana Agent to send data to Pyroscope using an example River configuration file for the Grafana Agent in Flow mode.
-Make sure you have [Grafana Agent in Flow mode](/docs/agent/latest/flow/setup/install/) installed.
+This procedure can be used with either Grafana Alloy or Grafana Agent collector.
+You can use the sample collector configuration file to send data to Pyroscope.
+This configuration file works for either Grafana Alloy or Grafana Agent in Flow mode.
+
+Grafana Alloy is the preferred collector.
+
+To install Alloy, refer to [Grafana Alloy installation](https://grafana.com/docs/alloy/latest/get-started/install/).
+
+{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
+
+If you are using legacy Grafana Agent Flow, use the [Grafana Agent in Flow mode](/docs/agent/latest/flow/setup/install/) documentation to install.
 
-### Prepare Grafana Agent Flow configuration file
+### Prepare the collector configuration file
 
-In the Grafana Agent Flow configuration file, you need to add at least two blocks: `pyroscope.write`
+In the Grafana Alloy or Grafana Agent Flow configuration file, you need to add at least two blocks: `pyroscope.write`
 and `pyroscope.scrape`.
 
 1. Add `pyroscope.write` block.
@@ -98,25 +106,30 @@ and `pyroscope.scrape`.
     }
 
     ```
+
 3. Save the changes to the file.
-### Start Grafana Agent Flow
 
-1. Start a local Pyroscope instance for testing purposes
+### Start the collector
+
+1. Start a local Pyroscope instance for testing purposes:
     ```bash
     docker run -p 4040:4040 grafana/pyroscope
     ```
-2. Start Grafana Agent
-    ```bash
-    grafana-agent-flow run conifguration.river
-    ```
+
+2. Start the collector:
+  * To start Grafana Alloy, replace `configuration.alloy` with your configuration file name: <br> `alloy run --stability.level=public-preview configuration.alloy`
+    The `stability.level` option is required for `pyroscope.scrape`. For more information about `stability.level`, refer to [The run command](https://grafana.com/docs/alloy/latest/reference/cli/run/#permitted-stability-levels) documentation.
+  * To start Grafana Agent, replace `configuration.river` with your configuration file name: <br> ` grafana-agent-flow run configuration.river`
+
 3. Open a browser to http://localhost:4040. The page should list profiles.
 
 ## Examples
 
 ### Send data to Grafana Cloud
 
 Your Grafana Cloud URL, username, and password can be found on the "Details Page" for Pyroscope from your stack on
-grafana.com. On this same page, create a token and use it as the Basic authentication password.
+grafana.com.
+On this same page, create a token and use it as the Basic authentication password.
 
 ```river
 pyroscope.write "write_job_name" {
@@ -140,6 +153,7 @@ pyroscope.write "write_job_name" {
           role = "pod"
   }
   ```
+
 2. Drop not running pods, create `namespace`, `pod`, `node` and `container` labels.
   Compose `service_name` label based on `namespace` and `container` labels.
   Select only services matching regex pattern `(ns1/.*)|(ns2/container-.*0)`.
@@ -206,21 +220,36 @@ pyroscope.write "write_job_name" {
 
 ### Exposing pprof endpoints
 
-If you don't use `http.DefaultServeMux`, you can register `/debug/pprof/*` handlers to your own `http.ServeMux`
+If you don't use `http.DefaultServeMux`, you can register `/debug/pprof/*` handlers to your own `http.ServeMux`:
+
 ```go
 var mux *http.ServeMux
 mux.Handle("/debug/pprof/", http.DefaultServeMux)
 ```
+
 Or, if you use gorilla/mux:
+
 ```go
 var router *mux.Router
 router.PathPrefix("/debug/pprof").Handler(http.DefaultServeMux)
 ```
 
 ## References
-[Example using grafana-agent](https://github.com/grafana/pyroscope/tree/main/examples/grafana-agent-auto-instrumentation).
-[pyroscope.scrape](/docs/agent/latest/flow/reference/components/pyroscope.scrape/)
-[pyroscope.write](/docs/agent/latest/flow/reference/components/pyroscope.write/)
-[discovery.kubernetes](/docs/agent/latest/flow/reference/components/discovery.kubernetes/)
-[discovery.docker](/docs/agent/latest/flow/reference/components/discovery.docker/)
-[discovery.relabel](/docs/agent/latest/flow/reference/components/discovery.relabel/)
+
+### Grafana Alloy
+
+- [Grafana Alloy](https://grafana.com/docs/alloy/latest/)
+- [pyroscope.scrape](/docs/alloy/latest/flow/reference/components/pyroscope.scrape/)
+- [pyroscope.write](/docs/alloy/latest/flow/reference/components/pyroscope.write/)
+- [discovery.kubernetes](/docs/alloy/latest/flow/reference/components/discovery.kubernetes/)
+- [discovery.docker](/docs/alloy/latest/flow/reference/components/discovery.docker/)
+- [discovery.relabel](/docs/alloy/latest/flow/reference/components/discovery.relabel/)
+
+### Grafana Agent
+
+- [Example using grafana-agent](https://github.com/grafana/pyroscope/tree/main/examples/grafana-agent-auto-instrumentation).
+- [pyroscope.scrape](/docs/agent/latest/flow/reference/components/pyroscope.scrape/)
+- [pyroscope.write](/docs/agent/latest/flow/reference/components/pyroscope.write/)
+- [discovery.kubernetes](/docs/agent/latest/flow/reference/components/discovery.kubernetes/)
+- [discovery.docker](/docs/agent/latest/flow/reference/components/discovery.docker/)
+- [discovery.relabel](/docs/agent/latest/flow/reference/components/discovery.relabel/)
@@ -1,13 +1,14 @@
 ---
-title: "Profiling Java using the Grafana Agent"
-menuTitle: "Profiling Java using the Grafana Agent"
-description: "Learn about using Grafana Agent for continuous profiling Java processes for performance optimization."
+title: "Profiling Java using Grafana Alloy or Agent"
+menuTitle: "Profiling Java using Alloy or Agent"
+description: "Learn about using Grafana Alloy or Agent for continuous profiling Java processes for performance optimization."
 weight: 20
 ---
 
-# Profiling Java using the Grafana Agent
+# Profiling Java using Grafana Alloy or Agent
+
+Grafana Alloy and Grafana Agent in [Flow mode](/docs/agent/latest/flow/) support Java profiling.
 
-Grafana Agent supports Java profiling in [Flow mode](/docs/agent/latest/flow/).
 Written in the
 [River](/docs/agent/latest/flow/config-language/) language, the configuration file is composed of components that are used to collect,
 transform, and send data.
@@ -70,11 +71,22 @@ The following arguments are supported:
 For more information on async-profiler configuration,
 see [profiler-options](https://github.com/async-profiler/async-profiler?tab=readme-ov-file#profiler-options).
 
-### Set privileges for the Agent
+### Set privileges for the collector
 
-You must run the agent as root and inside host pid namespace for the `pyroscope.java`
+You must run the collector, either Grafana Alloy (recommended) or Agent (legacy), as root and inside host `pid` namespace for the `pyroscope.java`
 and `discover.process` components to work.
 
+### Start the collector
+
+To start Grafana Alloy, 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`. For more information about `stability.level`, refer to [The run command](https://grafana.com/docs/alloy/latest/reference/cli/run/#permitted-stability-levels) documentation.
+
+To start Grafana Agent, replace `configuration.river` with your configuration file name:
+  ` grafana-agent-flow run configuration.river`
+
 ### 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.
@@ -182,7 +194,7 @@ pyroscope.write "example" {
 }
 ```
 
-### Profiling kubernetes pods
+### Profiling Kubernetes pods
 
 ```river
 
@@ -265,6 +277,18 @@ pyroscope.write "example" {
 For more information:
 
 * [Examples](https://github.com/grafana/pyroscope/tree/main/examples/grafana-agent-auto-instrumentation/java)
+
+### Grafana Alloy
+
+- [Grafana Alloy](https://grafana.com/docs/alloy/latest/)
+- [pyroscope.scrape](/docs/alloy/latest/flow/reference/components/pyroscope.scrape/)
+- [pyroscope.write](/docs/alloy/latest/flow/reference/components/pyroscope.write/)
+- [discovery.kubernetes](/docs/alloy/latest/flow/reference/components/discovery.kubernetes/)
+- [discovery.docker](/docs/alloy/latest/flow/reference/components/discovery.docker/)
+- [discovery.relabel](/docs/alloy/latest/flow/reference/components/discovery.relabel/)
+
+### Grafana Agent
+
 * [`pyroscope.java`](/docs/agent/next/flow/reference/components/pyroscope.java/)
 * [`discovery.process`](/docs/agent/next/flow/reference/components/discovery.process/)
 * [`discovery.kubernetes`](/docs/agent/next/flow/reference/components/discovery.kubernetes/)