Home

Awesome

<img src="docs/sources/assets/logo.png" height=226 alt="Grafana Beyla logo">

Grafana Beyla

Open source zero-code automatic instrumentation with eBPF and OpenTelemetry.

status badge

Introduction

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.

Community

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.

Getting Started

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.

Requirements

Available InstrumentationsSupported
HTTP/HTTPS/HTTP2
gRPC
SQL
Redis
Kafka

The Go instrumentation is limited to certain specific libraries.

Available Go InstrumentationsSupported
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.

Kubernetes

You can just trigger the Kubernetes descriptors in the deployments/ folder.

  1. 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 
    
  2. Deploy the Grafana Agent:

    kubectl apply -f deployments/02-grafana-agent.yml
    
  3. 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.

Development recipes

How to regenerate the eBPF Kernel binaries

The eBPF program is embedded into the pkg/internal/ebpf/bpf_* generated files. This step is generally not needed unless you change the C code in the bpf folder.

If you have Docker installed, you just need to run:

make docker-generate

If you can't install docker, you should locally install the following required packages:

dnf install -y kernel-devel make llvm clang glibc-devel.i686
make generate

Tested in Fedora 35, 38 and Red Hat Enterprise Linux 8.

Building Beyla from scratch

Development environment requirements

[!IMPORTANT] You need to run git lfs install once after installing the git-lfs package to deploy its global configuration

Common Makefile targets

Beyla's Makefile provides several specific-purpose build targets. The most common ones are:

Quickstart: cloning the repository and building Beyla

$ 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.

Formatting and linting code

Beyla uses linters to enforce our coding style and best practices:

All of them are enforced on pull requests as part of the Beyla github workflows. Additionally, you can invoke the linters manually:

clang-format is invoked automatically as a pre-commit git hook, so there is no explicit Makefile target for it.

Running VM tests

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

Credits

Part of the code is taken from: https://github.com/open-telemetry/opentelemetry-go-instrumentation