[DOC] Update index and java for Alloy (#3272)

* Update index and java for Alloy

* Apply suggestions from code review

* Update docs/sources/configure-client/grafana-agent/go_pull.md

* Update docs/sources/configure-client/grafana-agent/go_pull.md

* Updates for Java

* Apply suggestions from code review

docs/sources/configure-client/grafana-agent/_index.md

@@ -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.

docs/sources/configure-client/grafana-agent/go_pull.md

@@ -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(korniltsev) 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/)

docs/sources/configure-client/grafana-agent/java/_index.md

@@ -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/)