Open source zero-code automatic instrumentation with eBPF and OpenTelemetry.
Beyla has been donated to the CNCF OpenTelemetry Project, under the project name OpenTelemetry eBPF Instrumentation or OBI for short. We are in the process of vendoring most of the code that exists in the Beyla source repository from upstream. If you are working on a PR, unless it's related to documentation, please make the PR to the upstream repository. All Beyla current maintainers work full time on the upstream repository.
We expect that the process of migrating all development to the upstream repository to finish shortly. Some parts of the upstream codebase will likely be imported as a git submodule.
Beyla is a vendor agnostic, eBPF-based, OpenTelemetry/Prometheus application auto-instrumentation tool, which lets you easily get started with Application Observability. eBPF is used to automatically inspect application executables and the OS networking layer, allowing us to capture essential application observability events for HTTP/S and gRPC services. From these captured eBPF events, we produce OpenTelemetry web transaction trace spans and Rate-Errors-Duration (RED) metrics. As with most eBPF tools, all data capture and instrumentation occurs without any modifications to your application code or configuration.
To engage with the Beyla community and to chat with us on our community Slack channel, please invite yourself to the Grafana Slack, visit https://slack.grafana.com/ and join the #beyla channel.
We also run a monthly Beyla community call, on the second Wednesday of the month at 4pm UTC. You can find all of the details about our community call on the Grafana Community Calendar.
To try out Beyla, you need to run a network service for Beyla to instrument.
Beyla supports a wide range of programming languages (Go, Java, .NET, NodeJS, Python, Ruby, Rust, etc.),
so if you already have an example service you can use it.
If you don't have an example, you can download and run example-http-service.go from the examples/ directory:
curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/example-http-service/example-http-service.go
go run ./example-http-service.go
Next, generate some traffic. The following command will trigger a GET request to http://localhost:8080 every two seconds.
watch curl -s http://localhost:8080
Now that we have an example running, we are ready to download and run Beyla.
First, download and unpack the latest release from the GitHub releases page.
The release should contain the ./beyla executable.
Beyla supports multiple ways to find the service to be instrumented (by network port, executable name, process ID), and multiple exposition formats (Prometheus, OpenTelemetry metrics, Distributed Traces for Go, Single Span traces for other languages).
For getting started, we'll tell Beyla to instrument the service running on port 8080 (our example service) and expose metrics in Prometheus format on port 9400.
export BEYLA_PROMETHEUS_PORT=9400
export BEYLA_OPEN_PORT=8080
sudo -E ./beyla
Now, you should see metrics on http://localhost:9400/metrics.
See Documentation and the tutorials for more info.
- Linux with Kernel 5.8 or higher with BTF
enabled, or Linux distributions running RedHat Enterprise Linux 4.18 kernels build 348 and above as they have the required kernel backports. These include CentOS, AlmaLinux, and Oracle Linux. BTF became enabled by default on most Linux distributions with kernel 5.14 or higher.
You can check if your kernel has BTF enabled by verifying if
/sys/kernel/btf/vmlinuxexists on your system. If you need to recompile your kernel to enable BTF, the configuration optionCONFIG_DEBUG_INFO_BTF=ymust be set. - eBPF enabled on the host.
- For instrumenting Go programs, they must have been compiled with at least Go 1.17. We currently support Go applications built with a major Go version no earlier than 3 versions behind the current stable major release.
- Some level of elevated permissions to execute the instrumenter:
- On host systems, running Beyla requires
sudo. - For Kubernetes we have detailed configuration example on how to run with minimum required capabilities in the examples/k8s/unprivileged.yaml file.
- For docker compose, you need to setup Beyla as
privilegedcontainer or grant theSYS_ADMINcapability.
- On host systems, running Beyla requires
| Available Instrumentations | Supported |
|---|---|
| HTTP/HTTPS/HTTP2 | ✅ |
| gRPC | ✅ |
| SQL | ✅ |
| Redis | ✅ |
| Kafka | ✅ |
| MongoDB | ✅ |
The Go instrumentation is limited to certain specific libraries.
| Available Go Instrumentations | Supported |
|---|---|
Standard Go net/http |
✅ |
| Gorilla Mux | ✅ |
| Gin | ✅ |
| gRPC-Go | ✅ |
| Go x/net/http2 | ✅ |
| Go-Redis v9 | ✅ |
| Sarama Kafka | ✅ |
| kafka-Go | ✅ |
HTTPS instrumentation is limited to Go programs and libraries/languages using libssl3.
You can just trigger the Kubernetes descriptors in the deployments/ folder.
-
Provide your Grafana credentials. Use the following K8s Secret template to introduce the endpoints, usernames and API keys for Mimir and Tempo:
$ cp deployments/01-grafana-credentials.template.yml 01-grafana-credentials.yml $ # EDIT the fields $ vim 01-grafana-credentials.yml $ kubectl apply -f 01-grafana-credentials.yml -
Deploy the Grafana Agent:
kubectl apply -f deployments/02-grafana-agent.yml -
Deploy a demo app with the auto-instrumenter as a sidecar. You can use the blog example in the deployments/03-instrumented-app.yml file.
$ kubectl apply -f ./deployments/03-instrumented-app.yml $ kubectl port-forward service/goblog 8443:8443
You should be able to query traces and metrics in your Grafana board.
- go 1.25
- docker
- GNU make
- llvm >= 19
- clang >= 19
Beyla's Makefile provides several specific-purpose build targets. The most common ones are:
prereqs- install the build pre-requisitesdocker-generate- regenerates the eBPF binaries (preferred method)generate- regenerates the eBPF binaries 1compile- compiles thebeylabinary (but does not automatically regenerates the eBPF binaries)dev- equivalent tomake prereqs && make docker-generate && make compiletest- runs unit testsintegration-tests- runs integration tests - may requiresudoclang-format- formats C (eBPF) source code1vendor-obi- Downloads all the Opentelemetry-eBPF-Instrumentation (OBI) dependencies in a submodule, builds the BPF targets, and vendors it.
$ git clone https://github.com/grafana/beyla.git
$ cd beyla/
$ make dev
As described in the previous section, make dev takes care of setting up the build pre-requisites, including deploying a clang-format pre-commit hook.
After a successful compilation, binaries can be found in the bin/ subdirectory.
Beyla vendors part of the code from the opentelemetry-ebpf-instrumentation (OBI) project.
The code is incorporated as a Git submodule, named obi-src, in the .obi-src folder in the Beyla code base.
The contents of the .obi-src are used to build the BPF dependencies, and in a second step they are vendored
in the vendor/ directory.
Usually, you just need to run make vendor-obi to get the submodule data, compile BPF targets, and vendor them locally.
.obi-src folder is pinned to a concrete version of the OBI Git history. If you did changes in the upstream
opentelemetry-ebpf-instrumentation
repository, and want to update .obi-src to the latest contents, you'll need to run, from Beyla's project folder:
git submodule update --checkout --remote
git add .
(git add . is really important, otherwise when you try to recompile the code, the obi-src submodule might be
reverted to its original status).
Temporarily go to go.mod and change the first replace directive by your local OBI folder. For example:
-replace go.opentelemetry.io/obi => ./.obi-src
+replace go.opentelemetry.io/obi => ../opentelemetry-ebpf-instrumentationBuild the docker image with make dev-image-build.
replace directive in go.mod!
Beyla uses linters to enforce our coding style and best practices:
golangci-lintfor Go codeclang-formatfor formatting C codeclang-tidyfor static analysis of the C code
All of them are enforced on pull requests as part of the Beyla github workflows. Additionally, you can invoke the linters manually:
make lintinvokesgolangci-linton the Go codemake clang-tidyinvokesclang-tidyon the C/eBPF code
clang-format is invoked automatically as a pre-commit git hook, you can run it directly by using the Makefile clang-format target.
In addition to the test and integration-test Makefile targets, Beyla also runs select tests on QEMU virtual machines in order to be able to test different kernel versions. These tests are also part of our GitHub workflow, but it is also possible to run them manually using the following command:
$ sudo make -C test/vm KERNEL_VER=...
where KERNEL_VER is one of the supported kernel versions located in test/vm/kernels. For example, to run tests against kernel version 5.15.152, simply do:
$ sudo make -C test/vm KERNEL_VER=5.15.152
Part of the code is taken from: https://github.com/open-telemetry/opentelemetry-go-instrumentation