Menu

This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.

Open source

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.

Note

To run this component, Alloy requires administrative (sudo) privileges, or at least it needs to be granted the CAP_SYS_ADMIN and CAP_SYS_PTRACE capability. In Kubernetes environments, the AppArmor profile must be Unconfined for the Deployment or DaemonSet running Alloy.

Usage

alloy
beyla.ebpf "<LABEL>" {

}

Arguments

beyla.ebpf supports the following arguments:

NameTypeDescriptionDefaultRequired
open_portstringThe port of the running service for Beyla automatically instrumented with eBPF.""no
executable_namestringThe name of the executable to match for Beyla automatically instrumented with eBPF.""no
debugboolEnable debug mode for Beyla.falseno

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:

HierarchyBlockDescriptionRequired
routesroutesConfigures the routes to match HTTP paths into user-provided HTTP routes.no
attributesattributesConfigures the Beyla attributes for the component.no
attributes > kuberneteskubernetes attributesConfigures decorating of the metrics and traces with Kubernetes metadata of the instrumented Pods.no
discoverydiscoveryConfigures the discovery for instrumentable processes matching a given criteria.no
discovery > servicesservicesConfigures the services to discover for the component.no
discovery > services > kuberneteskubernetes servicesConfigures the Kubernetes services to discover for the component.no
discovery > exclude_servicesservicesConfigures the services to exclude for the component.no
discovery > exclude_services > kuberneteskubernetes servicesConfigures the Kubernetes services to exclude for the component.no
metricsmetricsConfigures which metrics Beyla exposes.no
metrics > networknetworkConfigures network metrics options for Beyla.no
outputoutputConfigures where to send received telemetry data.yes

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

NameTypeDescriptionDefaultRequired
enablestringEnable the Kubernetes metadata decoration.falseno
cluster_namestringThe name of the Kubernetes cluster.""no

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.

NameTypeDescriptionDefaultRequired
patternslist(string)List of provided URL path patterns to set the http.route trace/metric property[]no
ignore_patternslist(string)List of provided URL path patterns to ignore from http.route trace/metric property.[]no
ignore_modestringThe mode to use when ignoring patterns.""no
unmatchedstringSpecifies 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 *.

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.

NameTypeDescriptionDefaultRequired
namestringThe name of the service to match.""no
namespacestringThe namespace of the service to match.""no
open_portsstringThe port of the running service for Beyla automatically instrumented with eBPF.""no
exe_pathstringThe path of the running service for Beyla automatically instrumented with eBPF.""no

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.

NameTypeDescriptionDefaultRequired
namespacestringRegular expression of Kubernetes Namespaces to match.""no
pod_namestringRegular expression of Kubernetes Pods to match.""no
deployment_namestringRegular expression of Kubernetes Deployments to match.""no
statefulset_namestringRegular expression of Kubernetes StatefulSets to match.""no
replicaset_namestringRegular expression of Kubernetes ReplicaSets to match.""no
daemonset_namestringRegular expression of Kubernetes DaemonSets to match.""no
owner_namestringRegular expression of Kubernetes owners of running Pods to match.""no
pod_labelsmap(string)Key-value pairs of labels with keys matching Kubernetes Pods with the provided value as regular expression.{}no

metrics block

This block configures which metrics Beyla collects.

NameTypeDescriptionDefaultRequired
featureslist(string)List of features to enable for the metrics.["application"]no
instrumentationslist(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_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.

NameTypeDescriptionDefaultRequired
enabledboolEnable network metrics collection.falseno

output block

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

The following arguments are supported:

NameTypeDescriptionDefaultRequired
traceslist(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.

Exported fields

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

NameTypeDescription
targetslist(map(string))The targets that can be used to collect metrics of instrumented services with eBPF.

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
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
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:

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

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.