Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana Alloy Reference Components beyla beyla.ebpf

Public preview

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.

Usage

Alloy Copy

beyla.ebpf "<LABEL>" {

}

Arguments

beyla.ebpf supports the following arguments:

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.

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.

Blocks

The following blocks are supported inside the definition of beyla.ebpf:

The > symbol indicates deeper levels of nesting. For example,attributes > kubernetes refers to a kubernetes block defined inside an attributes block.

attributes block

This block allows you to configure how some attributes for metrics and traces are decorated.

It contains the following blocks:

kubernetes attributes block

If 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
• k8s.statefulset.name
• k8s.replicaset.name
• k8s.daemonset.name
• k8s.node.name
• k8s.pod.name
• 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.

routes block

This block is used to configure the routes to match HTTP paths into user-provided HTTP routes.

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

This block is used to configure the discovery for instrumentable processes matching a given criteria.

It contains the following blocks:

services block

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.

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

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.

output block

The output block configures a set of components to forward the resulting telemetry data to.

The following arguments are supported:

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.

Exported fields

The following fields are exported and can be referenced by other components.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

beyla.ebpf is only reported as unhealthy if given an invalid configuration.

Debug information

beyla.ebpf does not expose any component-specific debug information.

Example

Metrics

This example uses a prometheus.scrape component to collect metrics from beyla.ebpf of the specified port:

Alloy Copy

beyla.ebpf "default" {
    open_port = <OPEN_PORT>
}

prometheus.scrape "beyla" {
  targets = beyla.ebpf.default.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = <PROMETHEUS_REMOTE_WRITE_URL>

    basic_auth {
      username = <USERNAME>
      password = <PASSWORD>
    }
  }
}

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.

Traces

This example gets traces from beyla.ebpf and forwards them to otlp:

Alloy Copy

beyla.ebpf "default" {
    open_port = <OPEN_PORT>
    output {
        traces = [otelcol.processor.batch.default.input]
    }
}

otelcol.processor.batch "default" {
    output {
        traces  = [otelcol.exporter.otlp.default.input]
    }
}

otelcol.exporter.otlp "default" {
    client {
        endpoint = env("<OTLP_ENDPOINT>")
    }
}

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.

Compatible components

beyla.ebpf can accept arguments from the following components:

• Components that export OpenTelemetry otelcol.Consumer

beyla.ebpf has exports that can be consumed by the following components:

• Components that consume Targets