From cb9f7b07d82fecb572253cb90c181fa8bd643cbe Mon Sep 17 00:00:00 2001
From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>
Date: Mon, 13 Jan 2025 13:38:31 -0800
Subject: [PATCH] Clean up Alloy component docs (#2387)

* First pass at cleanup, pretty tables, sort lists

* Sort content, add badge

* Fix link

* Set link URL correctly

* Still fxing link targets

* One more tidy pass
---
 .../reference/components/beyla/beyla.ebpf.md  | 220 +++++++++---------
 1 file changed, 114 insertions(+), 106 deletions(-)

diff --git a/docs/sources/reference/components/beyla/beyla.ebpf.md b/docs/sources/reference/components/beyla/beyla.ebpf.md
index 2e19242f02..690f389273 100644
--- a/docs/sources/reference/components/beyla/beyla.ebpf.md
+++ b/docs/sources/reference/components/beyla/beyla.ebpf.md
@@ -21,7 +21,6 @@ To run this component, {{< param "PRODUCT_NAME" >}} requires administrative (`su
 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
@@ -36,52 +35,70 @@ 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 is 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__stage docs-labels__item">Required</span>
+
+The `output` block configures a set of components to forward the resulting telemetry data to.
+
+The following arguments are supported:
+
+Name     | Type                     | Description                          | Default | Required
+---------|--------------------------|--------------------------------------|---------|---------
+`traces` | `list(otelcol.Consumer)` | List of consumers to send traces to. | `[]`    | no
+
+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.
+
+### 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 will decorate the metrics and traces with Kubernetes metadata. The following labels will be added:
 
 - `k8s.namespace.name`
 - `k8s.deployment.name`
@@ -93,45 +110,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 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 `cluster_name` is not set, Beyla tries to detect the cluster name from the Kubernetes API.
+If `enable` is set to `false`, the Kubernetes metadata decorator is disabled.
 
-### 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 `*`.
+If `enable` is set to `autodetect`, Beyla tries to detect if it's running inside Kubernetes, and enables the metadata decoration if that's the case.
 
-### 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,81 +128,98 @@ 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
+
+`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.
 
 `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
+#### 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
-`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
+Name               | Type          | Description                                                                                                 | Default | Required
+-------------------|---------------|-------------------------------------------------------------------------------------------------------------|---------|---------
+`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.
 - `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.
 
-Name              | Type           | Description                                             | Default | Required
-------------------|----------------|---------------------------------------------------------|---------|---------
-`enabled`         | `bool`         | Enable network metrics collection.                      | `false` | no
+Name      | Type   | Description                        | Default | Required
+----------|--------|------------------------------------|---------|---------
+`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
+`ignore_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 does not 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`.
+- `metrics` discards only the metrics that match the `ignored_patterns`. No trace events are ignored.
+- `traces` discards only the traces that match the `ignored_patterns`. No metric 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 `ignore_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.
+  - Caution: This option could lead to a cardinality explosion on the ingester side.
+- `unset` leaves the `http.route` property as unset.
+- `wildcard` sets the `http.route` field property to a generic asterisk-based `/**` value.
 
 ## Exported fields
 
@@ -235,7 +241,9 @@ The exported targets use the configured [in-memory traffic][] address specified
 
 `beyla.ebpf` does not expose any component-specific debug information.
 
-## Example
+## Examples
+
+The following examples show you how to collect metricss and traces from `beyla.ebpf`.
 
 ### Metrics
 
@@ -303,16 +311,16 @@ Replace the following:
 
 [Grafana Beyla]: https://github.com/grafana/beyla
 [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
-[in-memory traffic]: ../../../../get-started/component_controller#in-memory-traffic
+[routes]: #routes
+[attributes]: #attributes
+[kubernetes attributes]: #kubernetes-attributes
+[kubernetes services]: #kubernetes-services
+[discovery]: #discovery
+[services]: #services
+[metrics]: #metrics
+[network]: #network
+[output]: #output
+[in-memory traffic]: ../../../../get-started/component_controller/#in-memory-traffic
 [run command]: ../../../cli/run/
 [scrape]: ../../prometheus/prometheus.scrape/