Using OpenTelemetry eBPF Instrumentation instead of Beyla

Table of contents:

Differences between OBI and Grafana
- Configuration
Beyla features that are missing in OBI

Grafana Beyla is the distribution of the OpenTelemetry eBPF Instrumentation (a.k.a. OBI) software that is currently supported by Grafana.

The Grafana Beyla code was donated in 2025 to the OpenTelemetry project as OBI, which is now maintained by a consortium of contributors that includes (but is not limited to) Grafana.

This document is aimed at helping users who want to use the upstream OBI distribution instead of Grafana Beyla. OBI works out of the box with the Grafana OTLP endpoint (or any intermediate OpenTelemetry/Prometheus collector), but there are some Beyla features that are not available in OBI. They are not indispensable for the correct functioning of OBI within the Grafana ecosystem, but users might require other OpenTelemetry projects to provide such features.

Differences between OBI and Grafana

Since its donation to OpenTelemetry, the code that implements all the eBPF-based auto-instrumentation has been moved to the OBI code repository and is imported as a library by the Grafana Beyla code repository. This means that every feature that is available in OBI is also available in Beyla.

However, not every feature in Beyla is currently available in OBI. While both are 100% open source, vendor-neutral solutions based on open standards and specifications, Beyla provides some extra features that smooth the adoption of eBPF-based auto-instrumentation within the Grafana ecosystem.

Also, the stable release cycles of the two projects are different. In this case, and unlike other open source projects, the Beyla release cycle is usually faster than OBI’s, so some features might be available in Beyla before they are in an official OBI release.

For metrics and attributes that don’t follow an OpenTelemetry semantic convention because none exists yet, Beyla prefixes the names with beyla_ while OBI prefixes them with obi_. For example, the network-level flow bytes metric is reported as beyla_network_flow_bytes_total in Beyla and obi_network_flow_bytes_total in OBI.

Configuration

Both Beyla and OBI follow the same YAML configuration schema, so any configuration example you might find in this documentation is generally compatible with OBI, with the exception of the Beyla features that are missing in OBI, which are listed in the following section.

As an alternative to the Beyla documentation, the OpenTelemetry site already documents how to configure OBI from a YAML configuration file.

A notable difference concerns configuring OBI with environment variables. OBI prefixes its configuration environment variables with OTEL_EBPF_* while Beyla prefixes them with BEYLA_* (Beyla also accepts the OTEL_EBPF_* prefix). The rest of the environment variable names remain the same in both cases.

For example, to set the logging verbosity level, OBI accepts the OTEL_EBPF_LOG_LEVEL environment variable, and Beyla accepts both BEYLA_LOG_LEVEL and OTEL_EBPF_LOG_LEVEL.

The OpenTelemetry common environment variables (for example OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_PROTOCOL) remain supported by both OBI and Beyla in the same way.

Beyla features that are missing in OBI

This section lists some features that are provided by Beyla but not by OBI:

Process metrics
Survey mode
Integration inside Grafana Alloy
Grafana AI Observability support
Connecting spans for Tempo service graph metrics

The following subsections provide upstream-only alternatives for these features.

Process metrics

Beyla provides the following metrics, which follow the OpenTelemetry semantic conventions for OS process metrics:

process.cpu.time
process.cpu.utilization
process.memory.usage
process.memory.virtual
process.disk.io
process.network.io

If you are using OBI but still require the above metrics, you need to install an instance of the OpenTelemetry Collector on each node and configure the Host Metrics Receiver to report process metrics.

Unlike the Collector’s Host Metrics Receiver, which sends metrics from all the processes in the system by default, Beyla only sends process metrics belonging to the services and applications that are instrumented. If you want to restrict the process metrics to only the processes reporting application-level metrics, you should manually configure the OpenTelemetry Collector to filter out processes that do not match the OBI Service Discovery configuration.

Survey mode

Beyla has a special survey mode that is aimed exclusively at discovering which of your currently uninstrumented services can be instrumented by Beyla. It enables faster auto-configuration of your services within Grafana Cloud’s Instrumentation Hub.

At the moment, there is no direct replacement for Beyla’s survey mode in OBI, but there is an ongoing initiative to port Beyla’s survey mode to OBI. We will update this document as the survey mode porting progresses.

Integration with Alloy or Collector

While Beyla can run as a standalone process, it can also run as an embedded component inside Grafana Alloy, an OpenTelemetry collector from Grafana. When it runs as an Alloy component, it can make use of some exclusive features, such as the integration with Fleet Management, which allows you to remotely manage multiple telemetry collector deployments at scale.

To achieve similar functionality with OBI, you need to follow these steps:

Build a custom Collector with OBI as a receiver.
Make sure the resulting collector integrates OpAMP, and check the Get started with Fleet Management and OpenTelemetry Collector documentation for integration instructions.

Grafana AI Observability support

OBI can generate spans and traces from your Generative AI clients. However, to make them fully compatible with Grafana AI, you need to manually configure your instrumentation pipeline:

Make sure OBI is exporting traces to your OpenTelemetry Collector (and your OpenTelemetry collector is forwarding them to Grafana Cloud)
In the OpenTelemetry collector:
- Decorate each span with an attribute named sigil.generation.id, and a value prefixed by gen_ followed by a random UUID. For example: gen_01234567-90ab-cdef-0123-456789abcdef
- Make sure each span contains the gen_ai.conversation.id attribute. If it does not exist, use a transform pipeline step to populate gen_ai.conversation.id with the value of the gen_ai.response.id attribute.
- (Optional) To reduce costs, filter out any span that doesn’t belong to a Generative AI workload, if you aren’t interested in it. For example, you can remove any span that doesn’t contain one of the gen_ai.* attributes if you aren’t interested in other types of workloads.

Using OBI with Grafana Cloud Application Observability and Knowledge Graph

With a base OBI installation, you can get basic functionality in Grafana Cloud Application Observability and Knowledge Graph. To get the most out of Application Observability, you need to make sure that OBI is configured to export the following families of metrics in the features section: