Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components beyla beyla.ebpf

Public preview

beyla.ebpf

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. The stability.level flag must be set to public-preview or below to use the component.

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.

debug enables debug mode for Beyla. This mode logs BPF logs, network logs, trace representation logs, and other debug information.

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.

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.

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.

metrics block

This block configures which metrics Beyla collects.

features is a list of features to enable for the metrics. The following features are available:

• application exports application-level metrics.
• application_spanexports 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.
• 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.
• kafka enables the collection of Kafka client/server message queue metrics.

network block

This block configures network metrics options for Beyla. You must append network to the features list in the metrics block to enable network metrics.

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
  honor_labels = true // required to keep job and instance labels
  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 = sys.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