需从 GitHub releases 页面下载并解压出 ./beyla 可执行文件,无包管理器安装步骤;内核需启用 BTF,可用 /sys/kernel/btf/vmlinux 是否存在来确认;Go 程序需用 Go 1.17 以上编译,且 HTTPS 插桩仅限 Go 或使用 libssl3 的程序。

export BEYLA_PROMETHEUS_PORT=9400
export BEYLA_OPEN_PORT=8080
sudo -E ./beyla需 Linux 内核 5.8 以上并启用 BTF(RHEL 4.18 build 348+ 亦可),宿主机需启用 eBPF;宿主机运行需 sudo,容器需 privileged 或 SYS_ADMIN 权限。README 未提及 GPU 或显存要求。
基于 eBPF 的零代码应用可观测性工具,自动采集 HTTP/gRPC 指标与链路追踪
基于 eBPF 自动采集 Web 应用和网络指标,无需改代码就能拿到可观测数据,适合快速接入监控和链路追踪。
核心能力
- 用 eBPF 自动探测进程与内核网络层,无需改代码
- 从捕获事件生成 OpenTelemetry 事务 Span 与 RED 指标
- 支持按端口、可执行文件名或进程 ID 定位服务
- 支持 Prometheus、OTel 指标及 Go 分布式追踪输出
- 覆盖 HTTP/HTTPS/gRPC/SQL/Redis/Kafka/MongoDB 协议
容易踩的坑
- v3.41.0pre-release2026-11-04 · 2026-11-04 16:29 UTC
查看更新说明
Changes from grafana/beyla:
- chore(deps): update dependency uvicorn to v0.54.0
- Add Ubuntu amd64 companion package PoC
- Include Java agent JAR in generated build artifacts (#3191)
- Add DEB package tests to CI
- Merge pull request #3190 from grafana/poc/non-kubernetes-packaging
- Bump Helm chart for Beyla v3.40.0
- Add experimental Beyla DEB release assets
- First topic reorg
- Second stage of reorg
- chore(deps): update dependency starlette to v1.10.0 (#3179)
- Add Beyla connection information metric support (#3192)
- Merge pull request #3197 from grafana/gregor/beyla-deb-release-publishing
- Merge pull request #3198 from grafana/docs/update-beyla-intro
- Merge pull request #3193 from grafana/helm-chart-bump/3.40.0
- Edit pass to clean up content and align with styles
- More refactoring, split obi topic, and validated statements in docs
- Correct styles and info flow
- Another clean-up pass for consistency
- Merge pull request #3201 from grafana/docs/update-beyla-intro-followup
- Clean up setup landing page and use section shortcode instead of hardcoded index
- Partial reorg of setup topics
- Last little shuffle for topic order
- Update to latest OBI
- update go mod and tests script
- Rework the Docker topic
- Merge pull request #3202 from grafana/docs/update-beyla-setup
- Merge remote-tracking branch 'origin/main' into docs/update-beyla-docker
- chore(deps): update dependency certifi to v2026.10.23 (#3199)
- docs: complete configuration reference and correct outdated settings (#3200)
- Merge pull request #3204 from grafana/docs/update-beyla-docker
- Fix the Helm commands. They would fail as documented
- Clarify the install sequence
- Explain Helm value merging better
- Fix the Beyla Helm chart ServiceMonitor section
- Fix the Beyla Helm chart OTLP credentials example
- Delete the manual TOC - not needed
- Document Beyla Helm chart privileges, context propagation, and presets
- Discovery default and apply steps
- Clean up headings and menu title
- Remove note, add an intro, add next steps links
- Tighten up wording, more active voice, remove vague steps, reoganise to more logical order
- Reference links, semantic line breaks, more active voice fixes
- Big cleanup for logical progression and task organization
- add config changes
- fix finder with new OBI
- add the config refresher
- tie in the new refresher logic
- add missing commit
- add docs and tests
- Merge branch 'main' into refresh_without_restart
- A few more minor adjustments
- Update page title, menu title, and description
- Remove manual TOC
- Tighten the Grafana Cloud Helm page intro
- Fix the Grafana Cloud Helm deploy steps
- fix env issue
- fix tests
- package(deb): use official Beyla package naming
- Clean up sequence and make the Grafana Cloud Helm deploy steps self-contained
- Add a little signposting for readers
- Small tweak
- Better explanation for ServiceMonitor
- Merge pull request #3208 from grafana/docs/update-beyla-helm
- Merge pull request #3210 from grafana/docs/update-beyla-helm-grafana-cloud
- Clean up code fenced content, fix typos
- Fix up intro, add prereqs, add running check and next steps
- Add info about chart managed Beyla keys
- Use replaceable vars style, fix headings, use active voice, spelling
- Convert the shell scripts which were invalid, to YAML
- fix: sed command failing on mac (#3212)
- Merge branch 'main' into refresh_without_restart
- ci: improve triage performance (#3213)
- Merge pull request #3207 from grafana/refresh_without_restart
- feat: use new dashboard-linter action
- Update links and refactor instructions
- Merge pull request #3214 from grafana/skl/dashboard-linter-github-action-replace
- Merge pull request #3205 from grafana/renovate/uvicorn-0.x
- package(deb): drop unreleased layout guards
- chore(deps): update otel/opentelemetry-collector-contrib docker tag to v0.164.0 (#3216)
- Merge pull request #3209 from grafana/gregor/beyla-package-naming-followup
- ci: add Beyla documentation PR previews (#3218)
- packag
- v3.38.1最新正式版2026-10-28 · 2026-10-28 14:49 UTC
Changes from grafana/beyla:
- Backport updates for Beyla v3.38.1 (#3196)
- Update obi submodule (v3.38.1)
- Release v3.38.1 artifacts
Changes from grafana/opentelemetry-ebpf-instrumentation:
- Backport Brotli security update to release-3.38
- Backport upstream CI fixes for release-3.38
- Fix release-3.38 CI compatibility and test fixtures
- Merge pull request open-telemetry/opentelemetry-ebpf-instrumentation#58 from grafana/security-3.38.1
- Release v3.38.1 artifacts
- v3.40.02026-10-26 · 2026-10-26 20:56 UTC
查看更新说明
Changes from grafana/beyla:
Enhancements
- introduce instrument_all_local mode for non-k8s
Fixes
- Fix injector state updates for empty selections
- fix(webhook): avoid deadlock between eligible deployment rebuild and store subscription
- fix(webhook): enrich a copy of the process info in addMetadata
Changes from grafana/opentelemetry-ebpf-instrumentation:
Enhancements
- Add .NET last-collection heap size metrics (open-telemetry/opentelemetry-ebpf-instrumentation#3697)
- feat: adapt ec2 detector logs to slog (open-telemetry/opentelemetry-ebpf-instrumentation#3780)
- sqlpp: resolve Couchbase prepared statements (open-telemetry/opentelemetry-ebpf-instrumentation#3744)
- Add GCE service name resolution (open-telemetry/opentelemetry-ebpf-instrumentation#3700)
- Add .NET8 exception counts runtime metrics (open-telemetry/opentelemetry-ebpf-instrumentation#3794)
- Extract MongoDB server hostname from configuration (open-telemetry/opentelemetry-ebpf-instrumentation#3634)
- fix(gpu): instrument per-thread default stream CUDA symbols (open-telemetry/opentelemetry-ebpf-instrumentation#3814)
- Add Azure Uniform VM Scale Set service name resolution (open-telemetry/opentelemetry-ebpf-instrumentation#3804)
- Add .NET 9+ exception metrics through the runtime Meter (open-telemetry/opentelemetry-ebpf-instrumentation#3832)
- Add .NET8+ GC heap fragmentation runtime metrics (open-telemetry/opentelemetry-ebpf-instrumentation#3887)
- Add Azure Flexible VM Scale Set service name resolution (open-telemetry/opentelemetry-ebpf-instrumentation#3901)
Fixes
- Messaging upstream conformance (open-telemetry/opentelemetry-ebpf-instrumentation#3739)
- HTTP attributes only on http spans without subtypes (open-telemetry/opentelemetry-ebpf-instrumentation#3740)
- gotracer: cut uprobe hits on the Go gRPC hot path (open-telemetry/opentelemetry-ebpf-instrumentation#3676)
- fix(otel): send JSON for OTLP traces when protocol is http/json (open-telemetry/opentelemetry-ebpf-instrumentation#3728)
- fix(collector): keep OBI running after the receiver Start context ends (open-telemetry/opentelemetry-ebpf-instrumentation#3745)
- fix: remove unused prometheus registry (open-telemetry/opentelemetry-ebpf-instrumentation#3702)
- tpinjector: stop injecting into sockets misclassified as HTTP/2 (open-telemetry/opentelemetry-ebpf-instrumentation#3715)
- Fix BPF verification after loop widening (open-telemetry/opentelemetry-ebpf-instrumentation#3759)
- Simplify read_skb_bytes (open-telemetry/opentelemetry-ebpf-instrumentation#3765)
- Cleanup code around symbol matching. (open-telemetry/opentelemetry-ebpf-instrumentation#3778)
- Update integration test shard weights (open-telemetry/opentelemetry-ebpf-instrumentation#3786)
- SQL++ spans outside Couchbase follow the SQL span names (open-telemetry/opentelemetry-ebpf-instrumentation#3754)
- HTTP metrics conformance (open-telemetry/opentelemetry-ebpf-instrumentation#3741)
- Fix attributes.select for metrics with non-normalized names (open-telemetry/opentelemetry-ebpf-instrumentation#3788)
- Validate OBI schema conformance to upstream schema (open-telemetry/opentelemetry-ebpf-instrumentation#3705)
- Keep a Pod's metadata when it reuses the IP of a finished Pod (open-telemetry/opentelemetry-ebpf-instrumentation#3789)
- fix(metadata): the retry timeout also bounds a hanging attempt (open-telemetry/opentelemetry-ebpf-instrumentation#3827)
- fix(bpf): skip debug-only traceparent formatting when debug is off (open-telemetry/opentelemetry-ebpf-instrumentation#3822)
- fix(k8s-cache): release dequeued subscriber events (open-telemetry/opentelemetry-ebpf-instrumentation#3807)
- fix(export): set instrumentation scope and schema_url on exported spans and metrics (open-telemetry/opentelemetry-ebpf-instrumentation#3797)
- bpf: key ssl connection maps by process (open-telemetry/opentelemetry-ebpf-instrumentation#3833)
- Make procEventMetadataDecorator.On non-blocking (open-telemetr
- v3.39.12026-10-22 · 2026-10-22 12:50 UTC
查看更新说明
Changes from grafana/beyla:
- Bump go versions to latest (3.39 branch) (#3183)
Changes from grafana/opentelemetry-ebpf-instrumentation:
- v3.39.02026-10-19 · 2026-10-19 07:26 UTC
查看更新说明
Changes from grafana/beyla:
- update obi
- update vendor
- add process metadata resolver in survey info
- Allow SDK injection with metrics only
- add sockets only survey selection criteria
- update obi again
- update obi
- fix up
- more cleanup
- add massive service filters
- test: cover metrics-only SDK injection
- Merge branch 'main' into survey_info_local
- fix merge
- Merge branch 'main' into survey_info_local
- fix merge again
- refactor for non-root selector
- fix tests
- update docs and schema
- add integration test
- Merge branch 'main' into fix/metrics-only-injection-3125
- test: construct metrics-only injector config directly
- Merge remote-tracking branch 'personal/fix/metrics-only-injection-3125' into fix/metrics-only-injection-3125
- Merge pull request #3159 from grafana/survey_info_local
- Merge branch 'main' into fix/metrics-only-injection-3125
- Merge pull request #3152 from loglapa/fix/metrics-only-injection-3125
- Bump Helm chart for Beyla v3.38.0 (#3161)
- Update OBI submodule (#3167)
- Update obi submodule (v3.39.0)
- Release v3.39.0 artifacts
Changes from grafana/opentelemetry-ebpf-instrumentation:
- Update module github.com/vektah/gqlparser/v2 to v2.5.60 (open-telemetry/opentelemetry-ebpf-instrumentation#3640)
- Rails: harvest routes for graphql engines (open-telemetry/opentelemetry-ebpf-instrumentation#3625)
- Update dependency graphql to "~> 2.6.0" (open-telemetry/opentelemetry-ebpf-instrumentation#3644)
- Generate the eBPF objects per architecture and in parallel (open-telemetry/opentelemetry-ebpf-instrumentation#3630)
- Update Docker images and fix compatibility fixtures (open-telemetry/opentelemetry-ebpf-instrumentation#3591)
- Update integration test pinned images (open-telemetry/opentelemetry-ebpf-instrumentation#3650)
- Update Docker (open-telemetry/opentelemetry-ebpf-instrumentation#3651)
- Update otel/ebpf-instrument Docker tag to v0.14.0 (open-telemetry/opentelemetry-ebpf-instrumentation#3652)
- Update otel/opentelemetry-collector-contrib Docker tag to v0.162.0 (open-telemetry/opentelemetry-ebpf-instrumentation#3653)
- weaver 0.27: read the report from /report, check health on the admin port, declare the manifest format (open-telemetry/opentelemetry-ebpf-instrumentation#3641)
- Refactor cloud metadata inventory maintenance (open-telemetry/opentelemetry-ebpf-instrumentation#3596)
- docs: add task-oriented AGENTS starting points (open-telemetry/opentelemetry-ebpf-instrumentation#3646)
- Prepare OBI for version v1.0.0-rc.1 (open-telemetry/opentelemetry-ebpf-instrumentation#3649)
- fix(bpf): replace the PID filter cache with a pid-indexed bitmap keyed in OBI's pid namespace (open-telemetry/opentelemetry-ebpf-instrumentation#3458)
- dotnet: extend .NET route harvesting (open-telemetry/opentelemetry-ebpf-instrumentation#3655)
- Fix duplicate target.info count when a pid moves to an existing service (open-telemetry/opentelemetry-ebpf-instrumentation#3665)
- Update jaegertracing/jaeger Docker tag to v2.22.0 (open-telemetry/opentelemetry-ebpf-instrumentation#3659)
- Resume integration shards from saved test results (open-telemetry/opentelemetry-ebpf-instrumentation#3629)
- Add .NET CPU count and time runtime metrics (open-telemetry/opentelemetry-ebpf-instrumentation#3647)
- oats/amqp: drop build-time host networking from compose files (open-telemetry/opentelemetry-ebpf-instrumentation#3668)
- Format and lint C code with LLVM 22 from the generator image (open-telemetry/opentelemetry-ebpf-instrumentation#3642)
- Assert histogram bucket boundaries in runtime exporter tests (open-telemetry/opentelemetry-ebpf-instrumentation#3660)
- Update dependency laravel/framework to v13.35.0 (open-telemetry/opentelemetry-ebpf-instrumentation#3658)
- Update Rust (open-telemetry/opentelemetry-ebpf-instrumentation#3682)
- Update dependency pino to v10.4.0 (open-telemetry/opentelemetry-ebpf-instrumentation#3680)
- Update Java (open-telemetry/opentelemetry-ebpf-instrumentation#3681)
- Add route53 support for Cloud met
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
Grafana Beyla
Open source zero-code automatic instrumentation with eBPF and OpenTelemetry.
Important Update for current and future Beyla contributors
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.
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
- 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.
Kubernetes
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.
Building Beyla from scratch
Development environment requirements
Minimum requirements
- go 1.26
- docker
- GNU make
Optional requirements
- llvm >= 19
- clang >= 19
Common Makefile targets
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-test- 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.
Quickstart
$ 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.
Managing code dependencies to opentelemetry-ebpf-instrumentation
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).
Developing with a local, development branch of opentelemetry-ebpf-instrumentation
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-instrumentation
Build the docker image with make dev-image-build.
⚠️ Before pushing your changes to our GitHub repo, don't forget to revert the replace directive in go.mod!
Formatting and linting code
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.
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 internal/testgenerated/vm KERNEL_VER=...
where KERNEL_VER is one of the supported kernel versions located in internal/testgenerated/vm/kernels. For example, to run tests against kernel version 5.15.152, simply do:
$ sudo make -C internal/testgenerated/vm KERNEL_VER=5.15.152
Credits
Part of the code is taken from: https://github.com/open-telemetry/opentelemetry-go-instrumentation