[DOC] Restructure Pyroscope documentation and share content (#3798)

* Restructure Pyroscope documentation and share content * Fix typo * Fix heading match for profile types * Restructure for configure server * Apply suggestions from code review Co-authored-by: Taylor C <[email protected]> * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Aleksandar Petrov <[email protected]> * Apply suggestions from code review Co-authored-by: Aleksandar Petrov <[email protected]> --------- Co-authored-by: Taylor C <[email protected]> Co-authored-by: Aleksandar Petrov <[email protected]>
grafana · Jan 7, 2025 · f9b116c · f9b116c
1 parent 7bfb866
commit f9b116c
Show file tree

Hide file tree

Showing 34 changed files with 507 additions and 303 deletions.
diff --git a/docs/sources/configure-client/grafana-alloy/_index.md b/docs/sources/configure-client/grafana-alloy/_index.md
@@ -92,7 +92,7 @@ This capability is not available in the legacy Grafana Agent.
 
 ### Set up profile receiving
 
-1. Configure your application with a Pyroscope SDK pointing to receive endpoint for Alloy. 
+1. Configure your application with a Pyroscope SDK pointing to the `pyroscope.receive_http` Alloy component.
 2. For step-by-step instructions, refer to the [Receive profiles from Pyroscope SDKs](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-alloy/receive_profiles) documentation.
 
 ## Next steps

diff --git a/docs/sources/configure-client/opentelemetry/ebpf-profiler.md b/docs/sources/configure-client/opentelemetry/ebpf-profiler.md
@@ -2,7 +2,7 @@
 title: OpenTelemetry profiling support
 menuTitle: OpenTelemetry profiling
 description: OpenTelemetry profiling support in Pyroscope
-weight: 10
+weight: 150
 ---
 
 # OpenTelemetry profiling support

diff --git a/docs/sources/configure-client/trace-span-profiles/go-span-profiles.md b/docs/sources/configure-client/trace-span-profiles/go-span-profiles.md
@@ -92,7 +92,7 @@ defer span.End()
 To view the span profiles in Grafana Tempo, you need to have a Grafana instance with a Tempo data source configured to link trace spans and profiles.
 Refer to the configuration documentation for [Grafana](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/configure-tempo-data-source) or [Grafana Cloud](/docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/configure-tempo-data-source).
 
-To learn how to set up Traces to profiles and view the span profiles, refer to [Traces to profiles]({{< relref "../../view-and-analyze-profile-data/profile-tracing/traces-to-profiles" >}}).
+To learn how to set up Traces to profiles and view the span profiles, refer to [Traces to profiles]({{< relref "../../view-and-analyze-profile-data/traces-to-profiles" >}}).
 
 
 ## Examples

diff --git a/docs/sources/configure-server/_index.md b/docs/sources/configure-server/_index.md
@@ -15,4 +15,4 @@ weight: 500
 
 The Pyroscope server is built to be horizontally scalable and to support organizations of all sizes.
 
-{{< section menuTitle="true" >}}
+{{< section withDescriptions="true">}}
diff --git a/docs/sources/configure-server/about-configurations.md b/docs/sources/configure-server/about-configurations.md
@@ -5,26 +5,35 @@ aliases:
 description: Learn about Pyroscope configuration and key guidelines to consider.
 menuTitle: About configurations
 title: About Pyroscope configurations
-weight: 10
+weight: 100
 ---
 
 # About Pyroscope configurations
 
-You can configure Pyroscope via a ([YAML](https://en.wikipedia.org/wiki/YAML)-based) configuration file or CLI (command-line-interface) flags. It is best to specify your configuration via the configuration file rather than CLI flags. Every parameter that is set in the configuration file can also be set via a corresponding CLI flag. If you specify both CLI flags and configuration parameters, CLI flags take precedence over corresponding values in a configuration file. You can specify the configuration file by using the `-config.file` CLI flag.
+You can configure Grafana Pyroscope using a ([YAML](https://en.wikipedia.org/wiki/YAML)-based) configuration file or CLI (command-line-interface) flags.
+You should specify your configuration using the configuration file rather than CLI flags.
+Every parameter that is set in the configuration file can also be set via a corresponding CLI flag.
+If you specify both CLI flags and configuration parameters, CLI flags take precedence over corresponding values in a configuration file.
+You can specify the configuration file by using the `-config.file` CLI flag.
 
 To see the CLI flags that you need to get started with Pyroscope, run the `pyroscope -help` command.
 
 To see the current configuration state of any component, use the `/api/v1/status/config` HTTP API endpoint.
 
 ## Operational considerations
 
-It is recommended to use a single configuration file and either pass it to all replicas of Pyroscope (if you are running multiple single-process Pyroscope replicas) or to all components of Pyroscope (if you are running Pyroscope as microservices). If you are running Pyroscope on Kubernetes, you can achieve this by storing the configuration file in a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) and mounting it in each Pyroscope container.
+You should use a single configuration file and either pass it to all replicas of Pyroscope (if you are running multiple single-process Pyroscope replicas) or to all components of Pyroscope (if you are running Pyroscope as microservices).
+If you are running Pyroscope on Kubernetes, you can achieve this by storing the configuration file in a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) and mounting it in each Pyroscope container.
 
-This helps avoid a common misconfiguration pitfall: while certain configuration parameters might look like they’re only needed by one type of component, they might in fact be used by multiple components. For example, the `-distributor.replication-factor` CLI flag is not only required by ingesters, but also by distributors and queriers.
+This helps avoid a common misconfiguration pitfall: while certain configuration parameters might look like they’re only needed by one type of component, they might in fact be used by multiple components.
+For example, the `-distributor.replication-factor` CLI flag is not only required by ingesters, but also by distributors and queriers.
 
 By using a single configuration file, you ensure that each component gets all the configuration that it needs without needing to track which parameter belongs to which component.
-There is no harm in passing a configuration that is specific to one component (such as an ingester) to another component (such as a querier). In such case, the configuration is simply ignored.
+There is no harm in passing a configuration that is specific to one component (such as an ingester) to another component (such as a querier).
+In such a case, the configuration is simply ignored.
 
-If necessary, you can use advanced CLI flags to override specific values on a particular Pyroscope component or replica. This can be helpful if you want to change a parameter that is specific to a certain component, without having to do a full restart of all other components.
+If necessary, you can use advanced CLI flags to override specific values on a particular Pyroscope component or replica.
+This is helpful if you want to change a parameter that's specific to a certain component, without having to do a full restart of all other components.
 
-The most common use case for CLI flags is to use the `-target` flag to run Pyroscope as microservices. By setting the `-target` CLI flag, all Pyroscope components share the same configuration file, but you can make them behave as a given component by specifying a `-target` command-line value, such as `-target=ingester` or `-target=querier`.
+The most common use case for CLI flags is to use the `-target` flag to run Pyroscope as microservices.
+By setting the `-target` CLI flag, all Pyroscope components share the same configuration file, but you can make them behave as a given component by specifying a `-target` command-line value, such as `-target=ingester` or `-target=querier`.
diff --git a/docs/sources/configure-server/about-ip-address-logging.md b/docs/sources/configure-server/about-ip-address-logging.md
@@ -3,14 +3,14 @@ aliases:
   - /docs/phlare/latest/operators-guide/configuring/about-ip-address-logging/
   - /docs/pyroscope/latest/configure-server/about-ip-address-logging/
 description: Troubleshoot errors by logging IP addresses of reverse proxies.
-menuTitle: About IP address logging of a reverse proxy
-title: About Grafana Pyroscope IP address logging of a reverse proxy
-weight: 60
+menuTitle: IP address logging of a reverse proxy
+title: IP address logging of a reverse proxy
+weight: 600
 ---
 
-# About Grafana Pyroscope IP address logging of a reverse proxy
+# IP address logging of a reverse proxy
 
-If a reverse proxy is used in front of Pyroscope, it might be difficult to troubleshoot errors.
+Note that using a reverse proxy in front of Grafana Pyroscope can make it difficult to troubleshoot errors.
 You can use the following settings to log the IP address passed along by the reverse proxy in headers such as `X-Forwarded-For`.
 
 - `-server.log-source-ips-enabled`

diff --git a/docs/sources/configure-server/about-tenant-ids.md b/docs/sources/configure-server/about-tenant-ids.md
@@ -3,26 +3,26 @@ aliases:
   - /docs/phlare/latest/operators-guide/configuring/about-tenant-ids/
   - /docs/phlare/latest/configure-server/about-tenant-ids/
 description: Learn about tenant ID restrictions.
-menuTitle: About tenant IDs
-title: About Grafana Pyroscope tenant IDs
-weight: 40
+menuTitle: Tenant IDs
+title: Tenant IDs
+weight: 200
 ---
 
-# About Grafana Pyroscope tenant IDs
+# Tenant IDs
 
 Grafana Pyroscope is a multi-tenant system where tenants can query profiles that include their tenant ID.
 Within a Grafana Pyroscope cluster, the tenant ID is the unique identifier of a tenant.
 The query takes the tenant ID from the `X-Scope-OrgID` parameter that exists in the HTTP header of each request, for example `X-Scope-OrgID: <TENANT-ID>`.
 
-To push profiles to Grafana Pyroscope for a specific tenant, refer to [Configure the Agent]({{< relref "../configure-client" >}}).
+To push profiles to Pyroscope for a specific tenant, refer to [Configure the Client](https://grafana.com/docs/pyroscope/<PYROSCOPE_SERVER>/configure-client/).
 
 > By default, multi-tenancy is disabled, the tenant ID is ignored and all profiles are stored and retrieved with the same tenant (`anonymous`).
 >
 >To enable multi-tenancy, add the `multitenancy_enabled` parameter to the Grafana Pyroscope configuration file and set it to `true`. Alternatively you can also use command line arguments to enable multi-tenancy, for example `--auth.multitenancy-enabled=true`.
 
 ## Restrictions
 
-Tenant IDs cannot be longer than 150 bytes or characters in length and can only include the following supported characters:
+Tenant IDs can't be longer than 150 bytes or characters in length and can only include the following supported characters:
 
 - Alphanumeric characters
   - `0-9`
@@ -38,6 +38,7 @@ Tenant IDs cannot be longer than 150 bytes or characters in length and can only
   - Open parenthesis (`(`)
   - Close parenthesis (`)`)
 
-> **Note:** For security reasons, `.` and `..` are not valid tenant IDs.
-
-All other characters, including slashes and whitespace, are not supported.
+{{< admonition type="note" >}}
+For security reasons, `.` and `..` aren't valid tenant IDs.
+All other characters, including slashes and whitespace, aren't supported.
+{{< /admonition >}}
diff --git a/docs/sources/configure-server/configure-shuffle-sharding/index.md b/docs/sources/configure-server/configure-shuffle-sharding/index.md
@@ -2,7 +2,7 @@
 description: Learn how to configure shuffle sharding.
 menuTitle: Shuffle sharding
 title: Configure Grafana Pyroscope shuffle sharding
-weight: 80
+weight: 800
 ---
 
 # Configure Grafana Pyroscope shuffle sharding

diff --git a/docs/sources/configure-server/configuring-memberlist.md b/docs/sources/configure-server/configuring-memberlist.md
@@ -1,14 +1,14 @@
 ---
 description: Learn how to configure Pyroscope memberlist.
-menuTitle: Configuring memberlist
-title: Configuring Pyroscope memberlist
-weight: 50
+menuTitle: Configure memberlist
+title: Configure Pyroscope memberlist
+weight: 500
 aliases:
   - /docs/phlare/latest/operators-guide/configuring/configuring-memberlist/
   - /docs/phlare/latest/configure-server/configuring-memberlist/
 ---
 
-# Configuring Pyroscope memberlist
+# Configure Pyroscope memberlist
 
 [Hash rings]({{< relref "../reference-pyroscope-architecture/hash-ring/index.md" >}}) are a distributed consistent hashing scheme and are widely used by Pyroscope for sharding and replication.
 Pyroscope only supports hash ring via the memberlist protocol.

diff --git a/docs/sources/configure-server/reference-configuration-parameters/index.md b/docs/sources/configure-server/reference-configuration-parameters/index.md
@@ -2,7 +2,7 @@
 description: Describes parameters used to configure Pyroscope.
 menuTitle: Configuration parameters
 title: Pyroscope configuration parameters
-weight: 70
+weight: 300
 aliases:
   - /docs/phlare/latest/operators-guide/configuring/reference-configuration-parameters/
   - /docs/phlare/latest/configure-server/reference-configuration-parameters/
@@ -629,7 +629,7 @@ ring:
 
       # Override the default cipher suite list (separated by commas). Allowed
       # values:
-      # 
+      #
       # Secure Ciphers:
       # - TLS_AES_128_GCM_SHA256
       # - TLS_AES_256_GCM_SHA384
@@ -644,7 +644,7 @@ ring:
       # - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
       # - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
       # - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-      # 
+      #
       # Insecure Ciphers:
       # - TLS_RSA_WITH_RC4_128_SHA
       # - TLS_RSA_WITH_3DES_EDE_CBC_SHA
@@ -812,7 +812,7 @@ lifecycler:
 
         # Override the default cipher suite list (separated by commas). Allowed
         # values:
-        # 
+        #
         # Secure Ciphers:
         # - TLS_AES_128_GCM_SHA256
         # - TLS_AES_256_GCM_SHA384
@@ -827,7 +827,7 @@ lifecycler:
         # - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
         # - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
         # - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-        # 
+        #
         # Insecure Ciphers:
         # - TLS_RSA_WITH_RC4_128_SHA
         # - TLS_RSA_WITH_3DES_EDE_CBC_SHA
@@ -1178,7 +1178,7 @@ sharding_ring:
 
       # Override the default cipher suite list (separated by commas). Allowed
       # values:
-      # 
+      #
       # Secure Ciphers:
       # - TLS_AES_128_GCM_SHA256
       # - TLS_AES_256_GCM_SHA384
@@ -1193,7 +1193,7 @@ sharding_ring:
       # - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
       # - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
       # - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-      # 
+      #
       # Insecure Ciphers:
       # - TLS_RSA_WITH_RC4_128_SHA
       # - TLS_RSA_WITH_3DES_EDE_CBC_SHA
@@ -1527,7 +1527,7 @@ sharding_ring:
 
       # Override the default cipher suite list (separated by commas). Allowed
       # values:
-      # 
+      #
       # Secure Ciphers:
       # - TLS_AES_128_GCM_SHA256
       # - TLS_AES_256_GCM_SHA384
@@ -1542,7 +1542,7 @@ sharding_ring:
       # - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
       # - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
       # - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-      # 
+      #
       # Insecure Ciphers:
       # - TLS_RSA_WITH_RC4_128_SHA
       # - TLS_RSA_WITH_3DES_EDE_CBC_SHA
@@ -1735,7 +1735,7 @@ backoff_config:
 [tls_insecure_skip_verify: <boolean> | default = false]
 
 # Override the default cipher suite list (separated by commas). Allowed values:
-# 
+#
 # Secure Ciphers:
 # - TLS_AES_128_GCM_SHA256
 # - TLS_AES_256_GCM_SHA384
@@ -1750,7 +1750,7 @@ backoff_config:
 # - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
 # - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
 # - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-# 
+#
 # Insecure Ciphers:
 # - TLS_RSA_WITH_RC4_128_SHA
 # - TLS_RSA_WITH_3DES_EDE_CBC_SHA
@@ -1948,7 +1948,7 @@ The `memberlist` block configures the Gossip memberlist.
 [tls_insecure_skip_verify: <boolean> | default = false]
 
 # Override the default cipher suite list (separated by commas). Allowed values:
-# 
+#
 # Secure Ciphers:
 # - TLS_AES_128_GCM_SHA256
 # - TLS_AES_256_GCM_SHA384
@@ -1963,7 +1963,7 @@ The `memberlist` block configures the Gossip memberlist.
 # - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
 # - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
 # - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-# 
+#
 # Insecure Ciphers:
 # - TLS_RSA_WITH_RC4_128_SHA
 # - TLS_RSA_WITH_3DES_EDE_CBC_SHA

diff --git a/docs/sources/configure-server/reference-configuration-parameters/index.template b/docs/sources/configure-server/reference-configuration-parameters/index.template
@@ -2,7 +2,7 @@
 description: Describes parameters used to configure Pyroscope.
 menuTitle: Configuration parameters
 title: Pyroscope configuration parameters
-weight: 70
+weight: 300
 aliases:
   - /docs/phlare/latest/operators-guide/configuring/reference-configuration-parameters/
   - /docs/phlare/latest/configure-server/reference-configuration-parameters/

diff --git a/docs/sources/configure-server/storage/_index.md b/docs/sources/configure-server/storage/_index.md
@@ -0,0 +1,12 @@
+---
+title: Configure storage
+menuTitle: Configure storage
+description: Learn about available storage options and how to configure them.
+weight: 400
+---
+
+# Configure storage
+
+Grafana Pyroscope provides storage configuration options for local and object storage.
+
+{{< section withDescriptions="true">}}
diff --git a/...onfigure-server/configure-disk-storage.md → ...-server/storage/configure-disk-storage.md b/...onfigure-server/configure-disk-storage.md → ...-server/storage/configure-disk-storage.md
@@ -1,22 +1,25 @@
 ---
-title: "Configure Pyroscope disk storage"
+title: "Configure disk storage"
 menuTitle: "Configure disk storage"
-description: ""
-weight: 30
+description: "Learn about the ingester component and how to configure disk storage for Pyroscope."
 aliases:
   - /docs/phlare/latest/configure-server/configure-disk-storage/
+  - ../configure-disk-storage/ # https://grafana.com/docs/pyroscope/latest/configure-server/configure-disk-storage/
 ---
 
-# Configure Pyroscope disk storage
+# Configure disk storage
 
-Pyroscope's [ingester] component processes the received profiling data.
-First it keeps the data organized in memory, in the so-called "head block". Once
-the size of the head block exceeds a threshold or the head block is older than
-`-pyroscopedb.max-block-duration` (by default 3 hours), the ingester will write
-the block to the local persistent disk (see [block format] for more detail about
-the block's layout). Each of those blocks are identified by an [ULID] and stored
-within Grafana Pyroscope's data path `-pyroscopedb.data-path=` (by default
-`./data`). This directory is organized by the following:
+The [ingester] component in Grafana Pyroscope processes the received profiling data.
+First it keeps the data organized in memory, in the so-called "head block".
+Once the size of the head block exceeds a threshold or the head block is older than
+`-pyroscopedb.max-block-duration` (by default 3 hours), the ingester writes
+the block to the local persistent disk.
+Refer to [block format] for more detail about the block's layout.
+
+Each of those blocks are identified by an [ULID] and stored
+within Pyroscope's data path `-pyroscopedb.data-path=` (by default
+`./data`).
+This directory is organized by the following:
 
 * `./<tenant-id>`: Each tenant has its own subdirectory with the following subdirectories:
    * `head/<block-id>`: Contains the current data still being written.
@@ -29,21 +32,22 @@ uploaded to the object store bucket.
 
 ## High disk utilization
 
-To avoid losing the most recent data, Pyroscope will remove the oldest blocks
+To avoid losing the most recent data, Pyroscope removes the oldest blocks
 when it detects that the volume on which the data path is located is close to
-running out of disk. This high utilization mode will be active every
+running out of disk space.
+The check for high disk utilization runs every
 `-pyroscopedb.retention-policy-enforcement-interval` when:
 
 * less than `-pyroscopedb.retention-policy-min-disk-available-percentage=0.05` of the total size of the volume is available and
 * the available disk space smaller then `-pyroscopedb.retention-policy-min-free-disk-gb=10`.
 
-The deletion will be logged like this:
+The deletion is logged like this:
 
 ```
 level=warn caller=pyroscopedb.go:231 ts=2022-10-05T13:19:09.770693308Z msg="disk utilization is high, deleted oldest block" path=data/anonymous/local/01GDZYHKKKY2ANY6PCJJZGT1N8
 ```
 
-[block format]: {{< relref "../reference-pyroscope-architecture/block-format/" >}}
+[block format]: {{< relref "../../reference-pyroscope-architecture/block-format/" >}}
 [object-store]: {{< relref "./configure-object-storage-backend.md" >}}
 [ULID]: https://github.com/ulid/spec
-[ingester]: {{< relref "../reference-pyroscope-architecture/components/ingester.md" >}}
+[ingester]: {{< relref "../../reference-pyroscope-architecture/components/ingester.md" >}}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,4 +15,4 @@ weight: 500

		The Pyroscope server is built to be horizontally scalable and to support organizations of all sizes.

		{{< section menuTitle="true" >}}
		{{< section withDescriptions="true">}}