docs: Validate beyla.ebpf component topic and consolidate examples

[clayton-cornell]

Cleanup on the beyla.ebpf topic

1. Added HTML comments to the output block section regarding some issues found during validation that could not be confirmed well enough for doc changes
2. Added some other HTML comments for future followup
3. Added a review date in the frontmatter
4. Found a deprecated arg and updated arg table
5. Fixed product variable name use
6. Added missing supported values for instrumentations
7. Removed duplicated example
8. Stripped out the big examples at the bottom of the topic
9. Added a link out to the Alloy scenario that provides a fully runnable example showing the same features as the old example that was stripped out.

[github-actions]

💻 Deploy preview available (docs: Validate beyla.ebpf component topic and consolidate examples):

• https://deploy-preview-alloy-6796-zb444pucvq-vp.a.run.app/docs/alloy/next/

[Copilot]

Pull request overview

This PR updates the beyla.ebpf component reference docs to better reflect current validation behavior, remove/condense large examples, and align argument/reference tables with the underlying component configuration.

Changes:

• Clarifies when the output block is required (and updates the block-requiredness indicators accordingly).
• Updates argument documentation (adds log_level, marks debug as deprecated, and expands supported values lists).
• Consolidates and trims examples, linking out to an Alloy scenario for a complete runnable configuration.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

docs/sources/reference/components/beyla/beyla.ebpf.md:1095

• The example uses otelcol.exporter.otlp.<LABEL>.input, which isn’t valid Alloy syntax inside a config block (angle brackets aren’t allowed in identifiers) and the referenced exporter isn’t defined in the example. This makes the snippet fail alloy validate even after filling in <OPEN_PORT>/<SERVICE_NAME>.

  output {
    traces = [otelcol.exporter.otlp.<LABEL>.input]
  }
}

docs/sources/reference/components/beyla/beyla.ebpf.md:1103

• After adding an OTLP exporter to the example, the placeholder list should include <OTLP_ENDPOINT> so readers know what to substitute.

* _`<LABEL>`_: A unique label for the component instance.
* _`<OPEN_PORT>`_: The port of the running service to instrument with eBPF.
* _`<SERVICE_NAME>`_: The name to assign to the instrumented service in exported metrics and traces.

docs/sources/reference/components/beyla/beyla.ebpf.md:268

• The note overstates the validation rule: an empty traces {} block is valid without output, but setting traces.instrumentations or traces.sampler requires output.traces (otherwise Alloy fails validation). Also, the local [traces]: #traces reference definition is redundant because the link is already defined earlier in the file.

{{< admonition type="note" >}}
If you configure the [`traces`][traces] block, you must also configure `output` with a `traces` destination, or Alloy returns a validation error at startup.

[traces]: #traces
{{< /admonition >}}

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

docs/sources/reference/components/beyla/beyla.ebpf.md:268

• This admonition adds a duplicate [traces]: #traces reference definition (there is already one earlier in the document) and has an extra leading space before "To export traces". Using an inline link avoids duplicate reference labels and keeps formatting consistent.

If you configure the [`traces`][traces] block, you must also define the `output` block, or {{< param "PRODUCT_NAME" >}} will return a validation error at startup.
 To export traces, configure `output.traces` with one or more destinations.

[traces]: #traces
{{< /admonition >}}

docs/sources/reference/components/beyla/beyla.ebpf.md:583

• wakeup_len is omitted from the generated Beyla config when it is left unset or explicitly set to 0 (see config_build.go), so documenting the default as 0 is misleading. Consider documenting it as unset (and that Beyla’s own default is used) to match the actual behavior.

| Name                    | Type       | Description                                                                   | Default      | Required |
|-------------------------|------------|---------------------------------------------------------------------------------|--------------|----------|
| `wakeup_len`            | `int`      | Number of messages to accumulate before wake up request.                        | `0`          | no       |
| `track_request_headers` | `bool`     | Enable tracking of request headers for `traceparent` fields.                    | `false`      | no       |
| `http_request_timeout`  | `duration` | Timeout for HTTP requests. When unset, Beyla uses its own default of `30s`.     | `""`         | no       |

docs/sources/reference/components/beyla/beyla.ebpf.md:261

• The output section says telemetry is "dropped" by default, but beyla.ebpf still exposes metrics via the Prometheus scrape target (targets export). Also, the underlying output block type accepts logs, but beyla.ebpf doesn’t emit logs, so it’s worth calling out that output.logs has no effect.

The `output` block is optional.
By default, telemetry data is dropped.
Configure `traces` to forward traces to OTel consumer components.
Configure `metrics` to forward metrics to OTel consumer components instead of, or in addition to, the Prometheus scrape path exposed via the `targets` export.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

docs/sources/reference/components/beyla/beyla.ebpf.md:262

• The output block description still implies it’s always optional and says “telemetry data is dropped”, but in the component validation output is conditionally required (when traces.instrumentations/traces.sampler is set, and when internal_metrics.exporter = "otel" requires output.metrics). This also conflicts with the earlier Blocks table which currently marks output as always required.

Consider updating this section to explicitly document the conditional requirement (and remove the TODO), and then align the Blocks table accordingly.

By default, telemetry data is dropped.
Configure `traces` to forward traces to OTel consumer components.
Configure `metrics` to forward metrics to OTel consumer components instead of, or in addition to, the Prometheus scrape path exposed via the `targets` export.

<!-- TODO: Validate output block requirement status and document internal_metrics block.

[ptodev]

Isn't every doc supposed to be up to date for its respective release? 😄

[clayton-cornell]

Yes... this is a metadata attribute that has existed for a long time and I wanted to see how it'd work as a "freshness" date for docs.

There's a lot of documentation that hasn't had a validation review for who knows how long. With this date, we can scan the markdown for topics that might need a refresh (AI is really good at this. but we can also script it).

This isn't a hard requirement, just something Jack and I have been chatting about off and on for a couple of months

[ptodev]

I don't mind if it's there, but not sure what it means. An old doc might still be accurate. It might be old just because it doesn't need a refresh.

I suppose AI can find a lot of out of date content by just looking for contradictions between different pages, and usage of attributes and blocks that are labeled as deprecated.

[clayton-cornell]

That's true. If an old doc is still valid and verified, the date is updated, and we let it ride for 6 months or whatever cycle we want to use to flag a "Hey is this still valid" check.

It's still up for discussion whether it'll be a good idea. :-)

[ptodev]

Nice to see links to Alloy scenarios in the example sections!

It'd be great to get feedback from the Beyla team on this PR and on the example in the scenarios repo. Currently Beyla is mostly for k8s, so a docker-only example may not be very representative or real world usage. But it might be ok.

[clayton-cornell]

100%. There needs to be some Beyla eyes on this. The validity review (code comparison) turned up some questions that need some expert eyes.