From 11d401cfa52aa8d00c027d6d278e5eb048f22713 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <clayton.cornell@grafana.com>
Date: Fri, 6 Sep 2024 10:35:54 -0700
Subject: [PATCH 1/2] Rework and reorganise Beyla component doc

---
 .../reference/components/beyla/beyla.ebpf.md  | 231 +++++++++---------
 1 file changed, 122 insertions(+), 109 deletions(-)

diff --git a/docs/sources/reference/components/beyla/beyla.ebpf.md b/docs/sources/reference/components/beyla/beyla.ebpf.md
index 2e19242f02..5eeb3f6671 100644
--- a/docs/sources/reference/components/beyla/beyla.ebpf.md
+++ b/docs/sources/reference/components/beyla/beyla.ebpf.md
@@ -14,19 +14,20 @@ title: beyla.ebpf
 
 The `beyla.ebpf` component is used as a wrapper for [Grafana Beyla][] which uses [eBPF][] to automatically inspect application executables and the OS networking layer, and capture trace spans related to web transactions and Rate Errors Duration (RED) metrics for Linux HTTP/S and gRPC services.
 You can configure the component to collect telemetry data from a specific port or executable path, and other criteria from Kubernetes metadata.
-The component exposes metrics that can be collected by a Prometheus scrape component, and traces that can be forwarded to an OTEL exporter component.
+The component exposes metrics that can be collected by a Prometheus scrape component, and traces that can be forwarded to an OTel exporter component.
 
 {{< admonition type="note" >}}
-To run this component, {{< param "PRODUCT_NAME" >}} requires administrative (`sudo`) privileges, or at least it needs to be granted the `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` capability.
+To run this component, {{< param "PRODUCT_NAME" >}} requires administrator privileges, or at least it must be granted the `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` capability.
 In Kubernetes environments, the [AppArmor profile must be `Unconfined`](https://kubernetes.io/docs/tutorials/security/apparmor/#securing-a-pod) for the Deployment or DaemonSet running {{< param "PRODUCT_NAME" >}}.
 {{< /admonition >}}
 
-
 ## Usage
 
 ```alloy
 beyla.ebpf "<LABEL>" {
-
+    output {
+        traces = [<LIST_OF_CONSUMERS>]
+    }
 }
 ```
 
@@ -36,52 +37,71 @@ beyla.ebpf "<LABEL>" {
 
 Name              | Type     | Description                                                                         | Default | Required
 ------------------|----------|-------------------------------------------------------------------------------------|---------|---------
-`open_port`       | `string` | The port of the running service for Beyla automatically instrumented with eBPF.     | `""`    | no
-`executable_name` | `string` | The name of the executable to match for Beyla automatically instrumented with eBPF. | `""`    | no
 `debug`           | `bool`   | Enable debug mode for Beyla.                                                        | `false` | no
+`executable_name` | `string` | The name of the executable to match for Beyla automatically instrumented with eBPF. | `""`    | no
+`open_port`       | `string` | The port of the running service for Beyla automatically instrumented with eBPF.     | `""`    | no
 
-`open_port` accepts a comma-separated list of ports (for example, `80,443`), and port ranges (for example, `8000-8999`).
-If the executable matches only one of the ports in the list, it is considered to match the selection criteria.
+`debug` enables debug mode for Beyla. This mode logs BPF logs, network logs, trace representation logs, and other debug information.
 
 `executable_name` accepts a regular expression to be matched against the full executable command line, including the directory where the executable resides on the file system.
 
-`debug` enables debug mode for Beyla. This mode logs BPF logs, network logs, trace representation logs, and other debug information.
+`open_port` accepts a comma-separated list of ports, for example, `80,443`, and port ranges, for example, `8000-8999`.
+If the executable matches only one of the ports in the list, it's considered to match the selection criteria.
 
 ## Blocks
 
 The following blocks are supported inside the definition of `beyla.ebpf`:
 
-Hierarchy               | Block                     | Description                                                                                        | Required
-------------------------|---------------------------|----------------------------------------------------------------------------------------------------|---------
-routes                  | [routes][]                | Configures the routes to match HTTP paths into user-provided HTTP routes.                          | no
-attributes              | [attributes][]            | Configures the Beyla attributes for the component.                                                 | no
-attributes > kubernetes | [kubernetes attributes][] | Configures decorating of the metrics and traces with Kubernetes metadata of the instrumented Pods. | no
-discovery               | [discovery][]             | Configures the discovery for instrumentable processes matching a given criteria.                   | no
-discovery > services    | [services][]              | Configures the services to discover for the component.                                                        | no
-discovery > services > kubernetes    | [kubernetes services][]   | Configures the Kubernetes services to discover for the component.                                | no
-discovery > exclude_services    | [services][]              | Configures the services to exclude for the component.                                                        | no
-discovery > exclude_services > kubernetes    | [kubernetes services][]   | Configures the Kubernetes services to exclude for the component.                                | no
-metrics                 | [metrics][]               | Configures which metrics Beyla exposes.                                                           | no
-metrics > network       | [network][]    | Configures network metrics options for Beyla.                                                      |no 
-output                  | [output][]                | Configures where to send received telemetry data.                                                  | yes
+Hierarchy                                 | Block                     | Description                                                                                        | Required
+------------------------------------------|---------------------------|----------------------------------------------------------------------------------------------------|---------
+output                                    | [output][]                | Configures where to send received telemetry data.                                                  | yes
+attributes                                | [attributes][]            | Configures the Beyla attributes for the component.                                                 | no
+attributes > kubernetes                   | [kubernetes attributes][] | Configures decorating of the metrics and traces with Kubernetes metadata of the instrumented Pods. | no
+discovery                                 | [discovery][]             | Configures the discovery for instrumentable processes matching a given criteria.                   | no
+discovery > exclude_services              | [services][]              | Configures the services to exclude for the component.                                              | no
+discovery > exclude_services > kubernetes | [kubernetes services][]   | Configures the Kubernetes services to exclude for the component.                                   | no
+discovery > services                      | [services][]              | Configures the services to discover for the component.                                             | no
+discovery > services > kubernetes         | [kubernetes services][]   | Configures the Kubernetes services to discover for the component.                                  | no
+metrics                                   | [metrics][]               | Configures which metrics Beyla exposes.                                                            | no
+metrics > network                         | [network][]               | Configures network metrics options for Beyla.                                                      | no
+routes                                    | [routes][]                | Configures the routes to match HTTP paths into user-provided HTTP routes.                          | no
 
 The `>` symbol indicates deeper levels of nesting.
 For example,`attributes > kubernetes` refers to a `kubernetes` block defined inside an `attributes` block.
 
-### attributes block
+### output
+
+<span class="badge docs-labels__product-oss docs-labels__item"><b>Required</b></span>
+
+The `output` block configures a set of components to forward the resulting telemetry data to.
+You must specify the `output` block, but all its arguments are optional.
+
+The following arguments are supported:
+
+Name      | Type                     | Description                           | Default | Required
+----------|--------------------------|---------------------------------------|---------|---------
+`traces`  | `list(otelcol.Consumer)` | List of consumers to send traces to.  | `[]`    | no
+
+By default, telemetry data is dropped.
+
+Configure the `traces` argument to send traces data to other components.
+
+### attributes
 
 This block allows you to configure how some attributes for metrics and traces are decorated.
 
 It contains the following blocks:
 
-#### kubernetes attributes block
+#### kubernetes attributes
+
+Name           | Type     | Description                                | Default | Required
+---------------|----------|--------------------------------------------|---------|---------
+`cluster_name` | `string` | The name of the Kubernetes cluster.        | `""`    | no
+`enable`       | `string` | Enable the Kubernetes metadata decoration. | `false` | no
 
-Name     | Type     | Description                                | Default | Required
----------|----------|--------------------------------------------|---------|---------
-`enable` | `string` | Enable the Kubernetes metadata decoration. | `false` | no
-`cluster_name` | `string` | The name of the Kubernetes cluster. | `""` | no
+If `cluster_name` isn't set, Beyla tries to detect the cluster name from the Kubernetes API.
 
-If set to `true`, Beyla will decorate the metrics and traces with Kubernetes metadata. The following labels will be added:
+If `enable` is set to `true`, Beyla decorates the metrics and traces with Kubernetes metadata. The following labels are added:
 
 - `k8s.namespace.name`
 - `k8s.deployment.name`
@@ -93,45 +113,17 @@ If set to `true`, Beyla will decorate the metrics and traces with Kubernetes met
 - `k8s.pod.uid`
 - `k8s.pod.start_time`
 
-If set to `false`, the Kubernetes metadata decorator will be disabled.
+If `enable` is set to `false`, the Kubernetes metadata decorator is disabled.
 
-If set to `autodetect`, Beyla will try to automatically detect if it is running inside Kubernetes, and enable the metadata decoration if that's the case.
+If `enable` is set to `autodetect`, Beyla tries to automatically detect if it's running inside Kubernetes, and enable the metadata decoration if that's the case.
 
-If `cluster_name` is not set, Beyla tries to detect the cluster name from the Kubernetes API.
-
-### routes block
-
-This block is used to configure the routes to match HTTP paths into user-provided HTTP routes.
-
-Name              | Type           | Description                                                                               | Default | Required
-------------------|----------------|-------------------------------------------------------------------------------------------|---------|---------
-`patterns`        | `list(string)` | List of provided URL path patterns to set the `http.route` trace/metric property          | `[]`    | no
-`ignore_patterns` | `list(string)` | List of provided URL path patterns to ignore from `http.route` trace/metric property.     | `[]`    | no
-`ignore_mode`     | `string`       | The mode to use when ignoring patterns.                                                   | `""`    | no
-`unmatched`       | `string`       | Specifies what to do when a trace HTTP path does not match any of the `patterns` entries. | `"heuristic"`    | no
-
-`patterns` and `ignored_patterns` are a list of patterns which a URL path with specific tags which allow for grouping path segments (or ignored them).
-The matcher tags can be in the `:name` or `{name}` format.
-`ignore_mode` properties are:
-- `all` discards metrics and traces matching the `ignored_patterns`.
-- `traces` discards only the traces that match the `ignored_patterns`. No metric events are ignored.
-- `metrics` discards only the metrics that match the `ignored_patterns`. No trace events are ignored.
-`unmatched` properties are:
-- `unset` leaves the `http.route` property as unset.
-- `path` copies the `http.route` field property to the path value.
-  - Caution: This option could lead to a cardinality explosion on the ingester side.
-- `wildcard` sets the `http.route` field property to a generic asterisk-based `/**` value.
-- `heuristic` automatically derives the `http.route` field property from the path value based on the following rules:
-  - Any path components that have numbers or characters outside of the ASCII alphabet (or `-` and _), are replaced by an asterisk `*`.
-  - Any alphabetical components that don’t look like words are replaced by an asterisk `*`.
-
-### discovery block
+### discovery
 
 This block is used to configure the discovery for instrumentable processes matching a given criteria.
 
 It contains the following blocks:
 
-### services block
+#### services
 
 In some scenarios, Beyla will instrument a wide variety of services, such as a Kubernetes DaemonSet that instruments all the services in a node.
 This block allows you to filter the services to instrument based on their metadata. If you specify other selectors in the same services entry,
@@ -139,60 +131,62 @@ the instrumented processes need to match all the selector properties.
 
 Name         | Type     | Description                                                                     | Default | Required
 -------------|----------|---------------------------------------------------------------------------------|---------|---------
-`name `      | `string` | The name of the service to match.                                               | `""`    | no
+`exe_path`   | `string` | The path of the running service for Beyla automatically instrumented with eBPF. | `""`    | no
+`name`       | `string` | The name of the service to match.                                               | `""`    | no
 `namespace`  | `string` | The namespace of the service to match.                                          | `""`    | no
 `open_ports` | `string` | The port of the running service for Beyla automatically instrumented with eBPF. | `""`    | no
-`exe_path`   | `string` | The path of the running service for Beyla automatically instrumented with eBPF. | `""`    | no
 
-`name` defines a name for the matching instrumented service.
-It is used to populate the `service.name` OTEL property and/or the `service_name` Prometheus property in the exported metrics/traces.
-`open_port` accepts a comma-separated list of ports (for example, `80,443`), and port ranges (for example, `8000-8999`).
-If the executable matches only one of the ports in the list, it is considered to match the selection criteria.
 `exe_path` accepts a regular expression to be matched against the full executable command line, including the directory where the executable resides on the file system.
 
-### kubernetes services block
+`name` defines a name for the matching instrumented service.
+It's used to populate the `service.name` OTel property or the `service_name` Prometheus property in the exported metrics/traces.
 
-This block allows you to filter the services to instrument based on their Kubernetes metadata. If you specify other selectors in the same services entry,
-the instrumented processes need to match all the selector properties.
+`open_port` accepts a comma-separated list of ports, for example, `80,443`, and port ranges,  for example, `8000-8999`.
+If the executable matches only one of the ports in the list, it's considered to match the selection criteria.
+
+#### kubernetes services
+
+This block allows you to filter the services to instrument based on their Kubernetes metadata.
+If you specify other selectors in the same services entry, the instrumented processes need to match all the selector properties.
 
 Name               | Type           | Description                                                                                                | Default | Required
 -------------------|----------------|-------------------------------------------------------------------------------------------------------------|---------|---------
-`namespace`        | `string`       | Regular expression of Kubernetes Namespaces to match.                                                       | `""`    | no
-`pod_name`         | `string`       | Regular expression of Kubernetes Pods to match.                                                             | `""`    | no
-`deployment_name`  | `string`       | Regular expression of Kubernetes Deployments to match.                                                      | `""`    | no
-`statefulset_name` | `string`       | Regular expression of Kubernetes StatefulSets to match.                                                     | `""`    | no
-`replicaset_name`  | `string`       | Regular expression of Kubernetes ReplicaSets to match.                                                      | `""`    | no
 `daemonset_name`   | `string`       | Regular expression of Kubernetes DaemonSets to match.                                                       | `""`    | no
+`deployment_name`  | `string`       | Regular expression of Kubernetes Deployments to match.                                                      | `""`    | no
+`namespace`        | `string`       | Regular expression of Kubernetes Namespaces to match.                                                       | `""`    | no
 `owner_name`       | `string`       | Regular expression of Kubernetes owners of running Pods to match.                                           | `""`    | no
 `pod_labels`       | `map(string)`  | Key-value pairs of labels with keys matching Kubernetes Pods with the provided value as regular expression. |  `{}`   | no
+`pod_name`         | `string`       | Regular expression of Kubernetes Pods to match.                                                             | `""`    | no
+`replicaset_name`  | `string`       | Regular expression of Kubernetes ReplicaSets to match.                                                      | `""`    | no
+`statefulset_name` | `string`       | Regular expression of Kubernetes StatefulSets to match.                                                     | `""`    | no
 
-### metrics block
+### metrics
 
 This block configures which metrics Beyla collects.
 
-Name              | Type           | Description                                                    | Default           | Required
-------------------|----------------|----------------------------------------------------------------|-------------------|---------
-`features`        | `list(string)` | List of features to enable for the metrics.         | `["application"]` | no
-`instrumentations`| `list(string)` | List of instrumentations to enable for the metrics. | `["*"]`           | no
+Name               | Type           | Description                                         | Default           | Required
+-------------------|----------------|-----------------------------------------------------|-------------------|---------
+`features`         | `list(string)` | List of features to enable for the metrics.         | `["application"]` | no
+`instrumentations` | `list(string)` | List of instrumentations to enable for the metrics. | `["*"]`           | no
 
 `features` is a list of features to enable for the metrics. The following features are available:
 
-- `application` exports application-level metrics.
-- `application_span`exports application-level metrics in traces span metrics format.
-- `application_service_graph` exports application-level service graph metrics.
 - `application_process` exports metrics about the processes that run the instrumented application.
+- `application_service_graph` exports application-level service graph metrics.
+- `application_span`exports application-level metrics in traces span metrics format.
+- `application` exports application-level metrics.
 - `network` exports network-level metrics.
 
 `instrumentations` is a list of instrumentations to enable for the metrics. The following instrumentations are available:
 
 - `*` enables all `instrumentations`. If `*` is present in the list, the other values are ignored.
-- `http` enables the collection of HTTP/HTTPS/HTTP2 application metrics.
 - `grpc` enables the collection of gRPC application metrics.
-- `sql` enables the collection of SQL database client call metrics.
-- `redis` enables the collection of Redis client/server database metrics.
+- `http` enables the collection of HTTP/HTTPS/HTTP2 application metrics.
 - `kafka` enables the collection of Kafka client/server message queue metrics.
+- `redis` enables the collection of Redis client/server database metrics.
+- `sql` enables the collection of SQL database client call metrics.
 
-### network block
+#### network
 
 This block configures network metrics options for Beyla. You must append `network` to the `features` list in the `metrics` block to enable network metrics.
 
@@ -200,20 +194,39 @@ Name              | Type           | Description
 ------------------|----------------|---------------------------------------------------------|---------|---------
 `enabled`         | `bool`         | Enable network metrics collection.                      | `false` | no
 
+### routes
 
-### output block
+This block is used to configure the routes to match HTTP paths into user-provided HTTP routes.
 
-The `output` block configures a set of components to forward the resulting telemetry data to.
+Name               | Type           | Description                                                                              | Default       | Required
+-------------------|----------------|------------------------------------------------------------------------------------------|---------------|---------
+`ignore_mode`      | `string`       | The mode to use when ignoring patterns.                                                  | `""`          | no
+`ignored_patterns` | `list(string)` | List of provided URL path patterns to ignore from `http.route` trace/metric property.    | `[]`          | no
+`patterns`         | `list(string)` | List of provided URL path patterns to set the `http.route` trace/metric property         | `[]`          | no
+`unmatched`        | `string`       | Specifies what to do when a trace HTTP path doesn't match any of the `patterns` entries. | `"heuristic"` | no
 
-The following arguments are supported:
+`ignore_mode` properties are:
 
-Name      | Type                     | Description                           | Default | Required
-----------|--------------------------|---------------------------------------|---------|---------
-`traces`  | `list(otelcol.Consumer)` | List of consumers to send traces to.  | `[]`    | no
+- `all` discards metrics and traces matching the `ignored_patterns`.
+- `traces` discards only the traces that match the `ignored_patterns`. No metric events are ignored.
+- `metrics` discards only the metrics that match the `ignored_patterns`. No trace events are ignored.
 
-You must specify the `output` block, but all its arguments are optional.
-By default, telemetry data is dropped.
-Configure the `traces` argument to send traces data to other components.
+`patterns` and `ignored_patterns` are a list of patterns which a URL path with specific tags which allow for grouping path segments (or ignored them).
+The matcher tags can be in the `:name` or `{name}` format.
+
+`unmatched` properties are:
+
+- `heuristic` automatically derives the `http.route` field property from the path value based on the following rules:
+
+  - Any path components that have numbers or characters outside of the ASCII alphabet (or `-` and _), are replaced by an asterisk `*`.
+  - Any alphabetical components that don’t look like words are replaced by an asterisk `*`.
+
+- `path` copies the `http.route` field property to the path value.
+  {{< admonition type="caution" >}}
+  This option could lead to a cardinality explosion on the ingester side.
+  {{< /admonition >}}
+- `unset` leaves the `http.route` property as unset.
+- `wildcard` sets the `http.route` field property to a generic asterisk-based `/**` value.
 
 ## Exported fields
 
@@ -233,7 +246,7 @@ The exported targets use the configured [in-memory traffic][] address specified
 
 ## Debug information
 
-`beyla.ebpf` does not expose any component-specific debug information.
+`beyla.ebpf` doesn't expose any component-specific debug information.
 
 ## Example
 
@@ -268,8 +281,8 @@ Replace the following:
 
 - _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
 - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
-- _`<USERNAME>`_: The username to use for authentication to the remote_write API.
-- _`<PASSWORD>`_: The password to use for authentication to the remote_write API.
+- _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+- _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 ### Traces
 
@@ -301,20 +314,20 @@ Replace the following:
 - _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
 - _`<OTLP_ENDPOINT>`_: The endpoint of the OpenTelemetry Collector to send traces to.
 
-[Grafana Beyla]: https://github.com/grafana/beyla
+[attributes]: #attributes
+[discovery]: #discovery
 [eBPF]: https://ebpf.io/
-[routes]: #routes-block
-[attributes]: #attributes-block
-[kubernetes attributes]: #kubernetes-attributes-block
-[kubernetes services]: #kubernetes-services-block
-[discovery]: #discovery-block
-[services]: #services-block
-[metrics]: #metrics-block
-[network]: #network-block
-[output]: #output-block
+[Grafana Beyla]: https://github.com/grafana/beyla
 [in-memory traffic]: ../../../../get-started/component_controller#in-memory-traffic
+[kubernetes attributes]: #kubernetes-attributes
+[kubernetes services]: #kubernetes-services
+[metrics]: #metrics
+[network]: #network
+[output]: #output
+[routes]: #routes
 [run command]: ../../../cli/run/
 [scrape]: ../../prometheus/prometheus.scrape/
+[services]: #services
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 

From ce762456285af07d5a86c238e9a0fd7cb44c8dfa Mon Sep 17 00:00:00 2001
From: Clayton Cornell <clayton.cornell@grafana.com>
Date: Tue, 3 Dec 2024 13:34:39 -0800
Subject: [PATCH 2/2] testing some ideas for alternative layouts

---
 .../reference/components/beyla/beyla.ebpf.md  | 138 +++++++++---------
 1 file changed, 70 insertions(+), 68 deletions(-)

diff --git a/docs/sources/reference/components/beyla/beyla.ebpf.md b/docs/sources/reference/components/beyla/beyla.ebpf.md
index 5eeb3f6671..c64088ab0d 100644
--- a/docs/sources/reference/components/beyla/beyla.ebpf.md
+++ b/docs/sources/reference/components/beyla/beyla.ebpf.md
@@ -2,6 +2,10 @@
 canonical: https://grafana.com/docs/alloy/latest/reference/components/beyla/beyla.ebpf/
 aliases:
   - ../beyla.ebpf/ # /docs/alloy/latest/reference/components/beyla.ebpf/
+keywords:
+  - Grafana Beyla
+  - eBPF
+  - Beyla
 description: Learn about beyla.ebpf
 title: beyla.ebpf
 ---
@@ -12,9 +16,9 @@ title: beyla.ebpf
 
 {{< docs/shared lookup="stability/public_preview.md" source="alloy" version="<ALLOY_VERSION>" >}}
 
-The `beyla.ebpf` component is used as a wrapper for [Grafana Beyla][] which uses [eBPF][] to automatically inspect application executables and the OS networking layer, and capture trace spans related to web transactions and Rate Errors Duration (RED) metrics for Linux HTTP/S and gRPC services.
+The `beyla.ebpf` component is a wrapper for [Grafana Beyla][], which uses [eBPF][] to automatically inspect application executables and the OS networking layer and capture trace spans related to web transactions and Rate Errors Duration (RED) metrics for Linux HTTP/S and gRPC services.
 You can configure the component to collect telemetry data from a specific port or executable path, and other criteria from Kubernetes metadata.
-The component exposes metrics that can be collected by a Prometheus scrape component, and traces that can be forwarded to an OTel exporter component.
+The component exposes metrics that a Prometheus scrape component can collect and traces that can be forwarded to an OTel exporter component.
 
 {{< admonition type="note" >}}
 To run this component, {{< param "PRODUCT_NAME" >}} requires administrator privileges, or at least it must be granted the `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` capability.
@@ -52,26 +56,24 @@ If the executable matches only one of the ports in the list, it's considered to
 
 The following blocks are supported inside the definition of `beyla.ebpf`:
 
-Hierarchy                                 | Block                     | Description                                                                                        | Required
-------------------------------------------|---------------------------|----------------------------------------------------------------------------------------------------|---------
-output                                    | [output][]                | Configures where to send received telemetry data.                                                  | yes
-attributes                                | [attributes][]            | Configures the Beyla attributes for the component.                                                 | no
-attributes > kubernetes                   | [kubernetes attributes][] | Configures decorating of the metrics and traces with Kubernetes metadata of the instrumented Pods. | no
-discovery                                 | [discovery][]             | Configures the discovery for instrumentable processes matching a given criteria.                   | no
-discovery > exclude_services              | [services][]              | Configures the services to exclude for the component.                                              | no
-discovery > exclude_services > kubernetes | [kubernetes services][]   | Configures the Kubernetes services to exclude for the component.                                   | no
-discovery > services                      | [services][]              | Configures the services to discover for the component.                                             | no
-discovery > services > kubernetes         | [kubernetes services][]   | Configures the Kubernetes services to discover for the component.                                  | no
-metrics                                   | [metrics][]               | Configures which metrics Beyla exposes.                                                            | no
-metrics > network                         | [network][]               | Configures network metrics options for Beyla.                                                      | no
-routes                                    | [routes][]                | Configures the routes to match HTTP paths into user-provided HTTP routes.                          | no
+Hierarchy                                       | Block                                            | Description                                                                                        | Required
+------------------------------------------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------|---------
+output                                        | [output][output]                               | Configures where to send received telemetry data.                                                  | yes
+attributes                                    | [attributes][attributes]                       | Configures the Beyla attributes for the component.                                                 | no
+attributes<br>&nbsp;&nbsp;└──kubernetes                  | [kubernetes&nbsp;attributes][kubernetes attributes] | Configures decorating of the metrics and traces with Kubernetes metadata of the instrumented Pods. | no
+discovery                                     | [discovery][discovery]                         | Configures the discovery for instrumentable processes matching a given criteria.                   | no
+discovery<br>&nbsp;&nbsp;└──exclude_services                | [services][services]                           | Configures the services to exclude for the component.                                              | no
+discovery<br>&nbsp;&nbsp;└──exclude_services<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└──kubernetes | [kubernetes&nbsp;services][kubernetes services]     | Configures the Kubernetes services to exclude for the component.                                   | no
+discovery<br>&nbsp;&nbsp;└──services                        | [services][services]                           | Configures the services to discover for the component.                                             | no
+discovery<br>&nbsp;&nbsp;└──services<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└──kubernetes         | [kubernetes&nbsp;services][kubernetes services]     | Configures the Kubernetes services to discover for the component.                                  | no
+metrics                                       | [metrics][metrics]                             | Configures which metrics Beyla exposes.                                                            | no
+metrics<br>&nbsp;&nbsp;└──network                           | [network][network]                             | Configures network metrics options for Beyla.                                                      | no
+routes                                        | [routes][routes]                               | Configures the routes to match HTTP paths into user-provided HTTP routes.                          | no
 
 The `>` symbol indicates deeper levels of nesting.
 For example,`attributes > kubernetes` refers to a `kubernetes` block defined inside an `attributes` block.
 
-### output
-
-<span class="badge docs-labels__product-oss docs-labels__item"><b>Required</b></span>
+### output <span class="badge docs-labels__product-oss docs-labels__item"><b>Required</b></span> {#output}
 
 The `output` block configures a set of components to forward the resulting telemetry data to.
 You must specify the `output` block, but all its arguments are optional.
@@ -86,13 +88,13 @@ By default, telemetry data is dropped.
 
 Configure the `traces` argument to send traces data to other components.
 
-### attributes
+### attributes <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#attributes}
 
 This block allows you to configure how some attributes for metrics and traces are decorated.
 
 It contains the following blocks:
 
-#### kubernetes attributes
+#### kubernetes attributes <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#kubernetes-attributes}
 
 Name           | Type     | Description                                | Default | Required
 ---------------|----------|--------------------------------------------|---------|---------
@@ -101,33 +103,33 @@ Name           | Type     | Description                                | Default
 
 If `cluster_name` isn't set, Beyla tries to detect the cluster name from the Kubernetes API.
 
-If `enable` is set to `true`, Beyla decorates the metrics and traces with Kubernetes metadata. The following labels are added:
+If you set `enable` to `true`, Beyla decorates the metrics and traces with Kubernetes metadata. The following labels are added:
 
-- `k8s.namespace.name`
-- `k8s.deployment.name`
-- `k8s.statefulset.name`
-- `k8s.replicaset.name`
-- `k8s.daemonset.name`
-- `k8s.node.name`
-- `k8s.pod.name`
-- `k8s.pod.uid`
-- `k8s.pod.start_time`
+* `k8s.namespace.name`
+* `k8s.deployment.name`
+* `k8s.statefulset.name`
+* `k8s.replicaset.name`
+* `k8s.daemonset.name`
+* `k8s.node.name`
+* `k8s.pod.name`
+* `k8s.pod.uid`
+* `k8s.pod.start_time`
 
-If `enable` is set to `false`, the Kubernetes metadata decorator is disabled.
+If you set `enable` to `false`, the Kubernetes metadata decorator is disabled.
 
-If `enable` is set to `autodetect`, Beyla tries to automatically detect if it's running inside Kubernetes, and enable the metadata decoration if that's the case.
+If you set `enable` to `autodetect`, Beyla tries to automatically detect if it's running inside Kubernetes, and enable the metadata decoration if that's the case.
 
-### discovery
+### discovery <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#discovery}
 
 This block is used to configure the discovery for instrumentable processes matching a given criteria.
 
 It contains the following blocks:
 
-#### services
+#### services <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#services}
 
-In some scenarios, Beyla will instrument a wide variety of services, such as a Kubernetes DaemonSet that instruments all the services in a node.
-This block allows you to filter the services to instrument based on their metadata. If you specify other selectors in the same services entry,
-the instrumented processes need to match all the selector properties.
+In some scenarios, Beyla instruments a wide variety of services, such as a Kubernetes DaemonSet that instruments all the services in a node.
+This block allows you to filter the services to instrument based on their metadata.
+If you specify other selectors in the same services entry, the instrumented processes need to match all the selector properties.
 
 Name         | Type     | Description                                                                     | Default | Required
 -------------|----------|---------------------------------------------------------------------------------|---------|---------
@@ -144,7 +146,7 @@ It's used to populate the `service.name` OTel property or the `service_name` Pro
 `open_port` accepts a comma-separated list of ports, for example, `80,443`, and port ranges,  for example, `8000-8999`.
 If the executable matches only one of the ports in the list, it's considered to match the selection criteria.
 
-#### kubernetes services
+#### kubernetes services <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#kubernetes-services}
 
 This block allows you to filter the services to instrument based on their Kubernetes metadata.
 If you specify other selectors in the same services entry, the instrumented processes need to match all the selector properties.
@@ -160,7 +162,7 @@ Name               | Type           | Description
 `replicaset_name`  | `string`       | Regular expression of Kubernetes ReplicaSets to match.                                                      | `""`    | no
 `statefulset_name` | `string`       | Regular expression of Kubernetes StatefulSets to match.                                                     | `""`    | no
 
-### metrics
+### metrics <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#metrics}
 
 This block configures which metrics Beyla collects.
 
@@ -171,22 +173,22 @@ Name               | Type           | Description
 
 `features` is a list of features to enable for the metrics. The following features are available:
 
-- `application_process` exports metrics about the processes that run the instrumented application.
-- `application_service_graph` exports application-level service graph metrics.
-- `application_span`exports application-level metrics in traces span metrics format.
-- `application` exports application-level metrics.
-- `network` exports network-level metrics.
+* `application_process` exports metrics about the processes that run the instrumented application.
+* `application_service_graph` exports application-level service graph metrics.
+* `application_span`exports application-level metrics in traces span metrics format.
+* `application` exports application-level metrics.
+* `network` exports network-level metrics.
 
 `instrumentations` is a list of instrumentations to enable for the metrics. The following instrumentations are available:
 
-- `*` enables all `instrumentations`. If `*` is present in the list, the other values are ignored.
-- `grpc` enables the collection of gRPC application metrics.
-- `http` enables the collection of HTTP/HTTPS/HTTP2 application metrics.
-- `kafka` enables the collection of Kafka client/server message queue metrics.
-- `redis` enables the collection of Redis client/server database metrics.
-- `sql` enables the collection of SQL database client call metrics.
+* `*` enables all `instrumentations`. If `*` is present in the list, the other values are ignored.
+* `grpc` enables the collection of gRPC application metrics.
+* `http` enables the collection of HTTP/HTTPS/HTTP2 application metrics.
+* `kafka` enables the collection of Kafka client/server message queue metrics.
+* `redis` enables the collection of Redis client/server database metrics.
+* `sql` enables the collection of SQL database client call metrics.
 
-#### network
+#### network <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#network}
 
 This block configures network metrics options for Beyla. You must append `network` to the `features` list in the `metrics` block to enable network metrics.
 
@@ -194,7 +196,7 @@ Name              | Type           | Description
 ------------------|----------------|---------------------------------------------------------|---------|---------
 `enabled`         | `bool`         | Enable network metrics collection.                      | `false` | no
 
-### routes
+### routes <span class="badge docs-labels__product-oss docs-labels__item"><b>Optional</b></span> {#routes}
 
 This block is used to configure the routes to match HTTP paths into user-provided HTTP routes.
 
@@ -207,26 +209,26 @@ Name               | Type           | Description
 
 `ignore_mode` properties are:
 
-- `all` discards metrics and traces matching the `ignored_patterns`.
-- `traces` discards only the traces that match the `ignored_patterns`. No metric events are ignored.
-- `metrics` discards only the metrics that match the `ignored_patterns`. No trace events are ignored.
+* `all` discards metrics and traces matching the `ignored_patterns`.
+* `traces` discards only the traces that match the `ignored_patterns`. No metric events are ignored.
+* `metrics` discards only the metrics that match the `ignored_patterns`. No trace events are ignored.
 
-`patterns` and `ignored_patterns` are a list of patterns which a URL path with specific tags which allow for grouping path segments (or ignored them).
+`patterns` and `ignored_patterns` are a list of patterns with a URL path with specific tags which allow you to group path segments, or ignore them.
 The matcher tags can be in the `:name` or `{name}` format.
 
 `unmatched` properties are:
 
-- `heuristic` automatically derives the `http.route` field property from the path value based on the following rules:
+* `heuristic` automatically derives the `http.route` field property from the path value based on the following rules:
 
-  - Any path components that have numbers or characters outside of the ASCII alphabet (or `-` and _), are replaced by an asterisk `*`.
-  - Any alphabetical components that don’t look like words are replaced by an asterisk `*`.
+  * Any path components that have numbers or characters outside of the ASCII alphabet or `-` and `_`, are replaced by an asterisk `*`.
+  * Any alphabetical components that don't look like words are replaced by an asterisk `*`.
 
-- `path` copies the `http.route` field property to the path value.
+* `path` copies the `http.route` field property to the path value.
   {{< admonition type="caution" >}}
   This option could lead to a cardinality explosion on the ingester side.
   {{< /admonition >}}
-- `unset` leaves the `http.route` property as unset.
-- `wildcard` sets the `http.route` field property to a generic asterisk-based `/**` value.
+* `unset` leaves the `http.route` property as unset.
+* `wildcard` sets the `http.route` field property to a generic asterisk-based `/**` value.
 
 ## Exported fields
 
@@ -279,10 +281,10 @@ prometheus.remote_write "demo" {
 
 Replace the following:
 
-- _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
-- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
-- _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
-- _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
+* _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
+* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
+* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 ### Traces
 
@@ -311,8 +313,8 @@ otelcol.exporter.otlp "default" {
 
 Replace the following:
 
-- _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
-- _`<OTLP_ENDPOINT>`_: The endpoint of the OpenTelemetry Collector to send traces to.
+* _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
+* _`<OTLP_ENDPOINT>`_: The endpoint of the OpenTelemetry Collector to send traces to.
 
 [attributes]: #attributes
 [discovery]: #discovery