[release/v1.9] [DOC] Convert Agent doc to Alloy (#3622)

--------- Co-authored-by: Aleksandar Petrov <[email protected]> (cherry picked from commit 7d12282) Co-authored-by: Kim Nylander <[email protected]>
grafana · Oct 11, 2024 · e696502 · e696502
1 parent b3ad536
commit e696502
Show file tree

Hide file tree

Showing 22 changed files with 317 additions and 335 deletions.
diff --git a/docs/sources/_index.md b/docs/sources/_index.md
@@ -30,7 +30,7 @@ cards:
       description: Learn how to install and configure Grafana Pyroscope with several examples.
     - title: Instrument your app and configure the client
       href: ./configure-client/
-      description: When sending profiles to Pyroscope, you can choose between SDK instrumentation and auto-instrumentation using the Grafana Agent. This document explains these two techniques and guide you when to choose each one.
+      description: When sending profiles to Pyroscope, you can choose between SDK instrumentation and auto-instrumentation using Grafana Alloy. This document explains these two techniques and helps you choose one.
     - title: Configure the server
       href: ./configure-server/
       description: Configure your Pyroscope server to meet your needs by setting disk storage, tenant IDs, memberlist, proxies, shuffle sharding, and more. You can also use the server HTTP API.
@@ -52,8 +52,8 @@ Grafana Pyroscope is a multi-tenant, continuous profiling aggregation system, al
 This integration enables a cohesive correlation of profiling data with existing metrics, logs, and traces.
 
 Explore continuous profiling data to gain insights into application performance.
-You can query and analyze production data in a structure way. 
-Use the Pyroscope UI or Grafana to visualize the data. 
+You can query and analyze production data in a structured way.
+Use the Pyroscope UI or Grafana to visualize the data.
 
 <!--video style="border-radius: 1%; width: 75%; display: block; margin-left: auto; margin-right: auto;" autoplay loop>
   <source src="ui.webm" type="video/webm">

diff --git a/docs/sources/configure-client/_index.md b/docs/sources/configure-client/_index.md
@@ -11,15 +11,15 @@ weight: 300
 # Configure the client to send profiles
 
 Pyroscope is a continuous profiling database that allows you to analyze the performance of your applications.
-When sending profiles to Pyroscope, you can choose between two primary methods: SDK instrumentation and auto-instrumentation using Grafana Alloy or Grafana Agent.
+When sending profiles to Pyroscope, you can choose between two primary methods: SDK instrumentation and auto-instrumentation using Grafana Alloy.
 
 This document explains these two techniques and guide you when to choose each one.
 
 ![Pyroscope agent server diagram](https://grafana.com/media/docs/pyroscope/pyroscope_client_server_diagram_09_18_2024.png)
 
 ## About auto-instrumentation with Grafana Alloy or Agent collectors
 
-You can send data from your application using Grafana Alloy or Grafana Agent collectors.
+You can send data from your application using Grafana Alloy (preferred) or Grafana Agent (legacy) 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.
@@ -31,8 +31,8 @@ New installations should use Alloy.
 
 {{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
 
-The Grafana collectors is a component that runs alongside your application and periodically gathers profiling data from it.
-This method is suitable when you want to collect profiles from existing applications without modifying their source code.
+Alloy is a component that runs alongside your application and periodically gathers profiling data from it.
+This method is suitable when you want to collect profiles from applications without modifying their source code.
 This approach is simplified with the eBPF profiling option that doesn't necessitate pull or push mechanisms.
 
 Here's how it works:
@@ -57,25 +57,23 @@ Here's how to use Pyroscope SDKs:
 By using the Pyroscope SDKs, you have the flexibility to customize the profiling process according to your application's specific requirements.
 You can selectively profile specific sections of code or send profiles at different intervals, depending on your needs.
 
-## Choose Grafana Agent or Pyroscope SDK to send profiles
+## Choose Grafana Alloy or Pyroscope SDK to send profiles
 
-{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
-
-You can use Grafana Agent for auto-instrumentation or the Pyroscope instrumentation SDKs.
+You can use Grafana Alloy for auto-instrumentation or the Pyroscope instrumentation SDKs.
 The method you choose depends on your specific use case and requirements.
 
 Here are some factors to consider when making the choice:
 
-- Ease of setup: The Grafana Agent is an ideal choice for a quick and straightforward setup without modifying your application's code. Note that eBPF profiling supports some languages (for example, Golang) better than others. More robust support for Python, Java, and other languages are in development.
+- Ease of setup: Grafana Alloy is an ideal choice for a quick and straightforward setup without modifying your application's code. eBPF profiling supports some languages (for example, Golang, Python) better than others. More robust support for Java and other languages is in development.
 - Language support: If you want more control over the profiling process and your application is written in a language supported by the Pyroscope SDKs, consider using the SDKs.
 - Flexibility: The Pyroscope SDKs offer greater flexibility in terms of customizing the profiling process and capturing specific sections of code with labels. If you have particular profiling needs or want to fine-tune the data collection process, the SDKs would be your best bet.
 
 To get started, choose one of the integrations below:
 <table>
    <tr>
-      <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/go_pull"><img src="https://github-production-user-asset-6210df.s3.amazonaws.com/223048/257522425-48683963-91ae-4caf-8c52-ce131e25bd65.png" width="100px;" alt=""/><br />
-        <b>Grafana Agent</b></a><br />
-          <a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/go_pull/" title="Documentation">Documentation</a><br />
+      <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/go_pull"><img src="/media/docs/alloy/alloy_icon.png" width="100px;" alt=""/><br />
+        <b>Grafana Alloy</b></a><br />
+          <a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/go_pull/" title="Documentation">Documentation</a><br />
           <a href="https://github.com/grafana/pyroscope/tree/main/examples/grafana-agent-auto-instrumentation" title="examples">Examples</a>
       </td>
       <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/go_push/"><img src="https://user-images.githubusercontent.com/23323466/178160549-2d69a325-56ec-4e19-bca7-d460d400b163.png" width="100px;" alt=""/><br />
@@ -88,9 +86,9 @@ To get started, choose one of the integrations below:
           <a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/java/">Documentation</a><br />
           <a href="https://github.com/grafana/pyroscope/tree/main/examples/language-sdk-instrumentation/java/rideshare" title="java-examples">Examples</a>
       </td>
-      <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/ebpf"><img src="https://user-images.githubusercontent.com/23323466/178160548-e974c080-808d-4c5d-be9b-c983a319b037.png" width="100px;" alt=""/><br />
+      <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/ebpf"><img src="https://user-images.githubusercontent.com/23323466/178160548-e974c080-808d-4c5d-be9b-c983a319b037.png" width="100px;" alt=""/><br />
         <b>eBPF</b></a><br />
-          <a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/ebpf" title="Documentation">Documentation</a><br />
+          <a href="https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/ebpf" title="Documentation">Documentation</a><br />
           <a href="https://github.com/grafana/pyroscope/tree/main/examples/grafana-agent-auto-instrumentation/ebpf" title="examples">Examples</a>
       </td>
       <td align="center"><a href="https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/python/"><img src="https://user-images.githubusercontent.com/23323466/178160553-c78b8c15-99b4-43f3-a2a0-252b6c4862b1.png" width="100px;" alt=""/><br />
@@ -125,10 +123,12 @@ To get started, choose one of the integrations below:
 
 ## Enriching profile data
 
-You can add tags to your profiles to help correlate them with your other telemetry signals. Some common tags that are used are version, region, environment, request types, etc. You have the ability to add tags using both the SDK and the agent.
+You can add tags to your profiles to help correlate them with your other telemetry signals.
+Commonly used tags include version, region, environment, and request types.
+You have the ability to add tags using both the SDK and Alloy.
 
 Valid tag formats may contain ASCII letters and digits, as well as underscores. It must match the regex `[a-zA-Z_][a-zA-Z0-9_]`.
-In Pyroscope, a period (`.`) is not a valid character inside of tags and labels.
+In Pyroscope, a period (`.`) isn't a valid character inside of tags and labels.
 
 ## Assistance with Pyroscope
 

diff --git a/docs/sources/configure-client/grafana-agent/ebpf/setup-docker.md b/docs/sources/configure-client/grafana-agent/ebpf/setup-docker.md
diff --git a/.../configure-client/grafana-agent/_index.md → .../configure-client/grafana-alloy/_index.md b/.../configure-client/grafana-agent/_index.md → .../configure-client/grafana-alloy/_index.md
@@ -1,33 +1,42 @@
 ---
-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."
+title: "Grafana Alloy"
+menuTitle: "Grafana Alloy"
+description: "Send data from your application using Grafana Alloy."
 weight: 10
 aliases:
   - /docs/phlare/latest/configure-client/grafana-agent/
+  - ./grafana-agent # /docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-agent/
 ---
 
-# Grafana Alloy and Grafana Agent
+# Grafana Alloy
 
 You can send data from your application using Grafana Alloy (preferred) or Grafana Agent (legacy) 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.
+[Grafana Alloy](https://grafana.com/docs/alloy/<ALLOY_VERSION>/) 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 uses configuration files written in Alloy configuration syntax.
+For  more information, refer to the [Alloy configuration syntax](https://grafana.com/docs/alloy/<ALLOY_VERSION>/get-started/configuration-syntax/).
 
 Alloy is the recommended collector instead of Grafana Agent.
 New installations should use Alloy.
 
-{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
-
-Grafana Agent is a powerful tool for collecting and forwarding profiling data.
-With the introduction of support for eBPF and continuing support for Golang in pull mode, Grafana Agent has become even more versatile in its capabilities.
+The instructions in this section explain how to use Alloy.
 
 {{< admonition type="note" >}}
-Refer to [Available profiling types]({{< relref "../../view-and-analyze-profile-data/profiling-types#available-profiling-types" >}}) for a list of profile types supported.
+Refer to [Available profiling types]({{< relref "../../view-and-analyze-profile-data/profiling-types#available-profiling-types" >}}) for a list of supported profile types.
 {{< /admonition >}}
 
+## Legacy collector, Grafana Agent
+
+{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
+
+Grafana Agent is a legacy tool for collecting and forwarding profiling data.
+Agent supports for eBPF and Golang in pull mode.
+For information about Agent, refer to [Grafana Agent Flow](https://grafana.com/docs/agent/<AGENT_VERSION>/flow/).
+
+Instructions for using Grafana Agent are available in documentation for Pyroscope v1.8 and earlier.
+
 ## 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.
@@ -41,13 +50,15 @@ Benefits of eBPF profiling:
 ### Set up eBPF profiling
 
 1. Ensure your system runs a Linux kernel version 4.9 or newer.
-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. Install a collector, such as Alloy, on the target machine or container.
+1. Configure Alloy to use eBPF for profiling. Refer to the [eBPF documentation](/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-alloy/ebpf) for detailed steps.
 1. The collector collects eBPF profiles and sends them to the Pyroscope server.
 
 ### Supported languages
 
-This eBPF profiler only collects CPU profiles. Generally, natively compiled languages like C/C++, Go, and Rust are supported. Refer to [Troubleshooting unknown symbols][troubleshooting] for additional requirements.
+This eBPF profiler only collects CPU profiles.
+Generally, natively compiled languages like C/C++, Go, and Rust are supported.
+Refer to [Troubleshooting unknown symbols][troubleshooting] for additional requirements.
 
 Python is the only supported high-level language, as long as `python_enabled=true`.
 Other high-level languages like Java, Ruby, PHP, and JavaScript require additional work to show stack traces of methods in these languages correctly.
@@ -61,18 +72,18 @@ In pull mode, the collector periodically retrieves profiles from Golang applicat
 
 - Non-intrusive: No need to modify your application’s source code.
 - Centralized profiling: Suitable for environments with multiple Golang applications or microservices.
-- Automatic: The agent handles the pulling and sending of profiles, requiring minimal configuration.
+- Automatic: Alloy handles the pulling and sending of profiles, requiring minimal configuration.
 
 ### Set up Golang profiling in pull mode
 
 1. Ensure your Golang application exposes pprof endpoints.
-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. Install and configure Alloy on the same machine or container where your application runs.
+1. Ensure Alloy is set to pull mode and targeting the correct pprof endpoints. For step-by-step instructions, visit the [Go (Pull Mode)](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-alloy/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 collectors 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, Alloy collectors offer streamlined processes to gather essential profiling data.
 Choose the method that best fits your application and infrastructure needs.
 
-[troubleshooting]: /docs/alloy/latest/reference/components/pyroscope/pyroscope.ebpf/#troubleshooting-unknown-symbols
+[troubleshooting]: /docs/alloy/<ALLOY_VERSION>/reference/components/pyroscope/pyroscope.ebpf/#troubleshooting-unknown-symbols