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 topublic-preview
or below to use the component.
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.
Note
To run this component, Alloy requires administrative privileges, or at least it needs to be granted theCAP_SYS_ADMIN
andCAP_SYS_PTRACE
capability. In Kubernetes environments, the AppArmor profile must beUnconfined
for the Deployment or DaemonSet running Alloy.
Usage
beyla.ebpf "<LABEL>" {
}
Arguments
You can use the following arguments with beyla.ebpf
:
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.
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
You can use the following blocks with beyla.ebpf
:
The >
symbol indicates deeper levels of nesting.
For example,attributes > kubernetes
refers to a kubernetes
block defined inside an attributes
block.
output
Required
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.
attributes
The attributes
block configures how some attributes for metrics and traces are decorated.
It contains the following block:
kubernetes
attributes
This kubernetes
block configures the decorating of the metrics and traces with Kubernetes metadata from the instrumented Pods.
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:
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 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
The discovery
block configures the discovery for instrumentable processes matching a given criteria.
It contains the following blocks:
services
In some scenarios, Beyla instruments a wide variety of services, such as a Kubernetes DaemonSet that instruments all the services in a node.
The services
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.
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’s used to populate the service.name
OTel property 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’s considered to match the selection criteria.
kubernetes
services
This kubernetes
block filters 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
The metrics
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_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 allinstrumentations
. 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
The network
block configures network metrics options for Beyla. You must append network
to the features
list in the metrics
block to enable network metrics.
routes
The routes
block configures the routes to match HTTP paths into user-provided HTTP routes.
ignore_mode
properties are:
all
discards metrics and traces matching theignored_patterns
.metrics
discards only the metrics that match theignored_patterns
. No trace events are ignored.traces
discards only the traces that match theignored_patterns
. No metric events are ignored.
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 thehttp.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
path
copies thehttp.route
field property to the path value.Caution
This property could lead to a cardinality explosion on the ingester side.unset
leaves thehttp.route
property as unset.wildcard
sets thehttp.route
field property to a generic asterisk-based/**
value.
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
doesn’t expose any component-specific debug information.
Examples
The following examples show you how to collect metrics and traces from beyla.ebpf
.
Metrics
This example uses a prometheus.scrape
component to collect metrics from beyla.ebpf
of the specified port:
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 theremote_write
API.<PASSWORD>
: The password to use for authentication to theremote_write
API.
Traces
This example gets traces from beyla.ebpf
and forwards them to otlp
:
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
Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.