grafana/beyla

# of English and Chinese. 基于 eBPF 和 OpenTelemetry 的开源零代码自动插桩工具。 [](https://github.com/grafana/beyla/actions/workflows/publish_gar_release.yml) [](https://github.com/grafana/beyla/blob/main/LICENSE) ## 简介 Beyla 是一款厂商中立的、基于 eBPF 的、支持 OpenTelemetry/Prometheus 的应用自动插桩工具，能让您轻松入门应用可观测性。 eBPF 用于自动检测应用程序可执行文件和操作系统网络层，使我们能够捕获 HTTP/S 和 gRPC 服务的关键应用可观测性事件。 根据这些捕获的 eBPF 事件，我们生成 OpenTelemetry Web 事务跟踪跨度和速率-错误-持续时间 (RED) 指标。 与大多数 eBPF 工具类似，所有数据捕获和插桩操作均无需对您的应用代码或配置进行任何修改。 ## 入门指南 要试用 Beyla，您需要运行一个网络服务供 Beyla 进行插桩。 Beyla 支持多种编程语言（Go、Java、.NET、NodeJS、Python、Ruby、Rust 等）， 因此如果您已有示例服务，可以直接使用。 如果没有示例，可以从 `examples/` 目录下载并运行 `example-http-service.go`： ``` curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/example-http-service/example-http-service.go go run ./example-http-service.go ``` 接下来，生成一些流量。以下命令将每两秒向 http://localhost:8080 触发一次 GET 请求。 ``` watch curl -s http://localhost:8080 ``` 现在示例已运行，我们可以下载并运行 Beyla 了。 首先，从 [GitHub 发布页面](https://github.com/grafana/beyla/releases) 下载并解压最新版本。 发布版本应包含 `./beyla` 可执行文件。 Beyla 支持多种查找待插桩服务的方式（按网络端口、可执行文件名、进程 ID）， 以及多种导出格式（Prometheus、OpenTelemetry 指标、Go 的分布式跟踪、其他语言的单跨度跟踪）。 入门时，我们将配置 Beyla 插桩运行在端口 8080 上的服务（我们的示例服务），并在端口 9400 上以 Prometheus 格式暴露指标。 ``` export BEYLA_PROMETHEUS_PORT=9400 export BEYLA_OPEN_PORT=8080 sudo -E ./beyla ``` 现在，您应该能在 [http://localhost:9400/metrics](http://localhost:9400/metrics) 看到指标。 更多信息请参阅 [文档](https://grafana.com/docs/beyla/) 和 [教程](https://grafana.com/docs/beyla/latest/tutorial/)。 ## 要求 - Linux 内核版本 5.8 或更高，且需启用 [BTF](https://www.kernel.org/doc/html/latest/bpf/btf.html)，或运行 RedHat Enterprise Linux 4.18 内核构建版本 348 及以上的 Linux 发行版（因为它们包含所需的内核向后移植）。这些发行版包括 CentOS、AlmaLinux 和 Oracle Linux。BTF 在内核 5.14 或更高版本的大多数 Linux 发行版中默认启用。 您可以通过检查系统中是否存在 `/sys/kernel/btf/vmlinux` 来验证内核是否启用了 BTF。 如果需要重新编译内核以启用 BTF，则必须设置配置选项 `CONFIG_DEBUG_INFO_BTF=y`。 - 主机上已启用 eBPF。 - 对于 Go 程序的插桩，它们必须至少使用 Go 1.17 编译。我们目前支持的 Go 应用程序，其主要 **Go 版本不得低于当前稳定主要版本 3 个版本以上**。 - 执行插桩工具需要一定程度的提升权限： - 在主机系统上运行 Beyla 需要 `sudo` 权限。 - 对于 Kubernetes，我们在 [examples/k8s/unprivileged.yaml](./examples/k8s/unprivileged.yaml) 文件中有如何以最小所需能力运行的详细配置示例。 - 对于 docker compose，您需要将 Beyla 设置为 `privileged` 容器或授予 `SYS_ADMIN` 能力。 | 可用插桩项 | 支持情况 | |---------------------------------|----------| | HTTP/HTTPS/HTTP2 | ✅ | | gRPC | ✅ | | SQL | ✅ | | Redis | ✅ | | Kafka | ✅ | | MongoDB | ✅ | Go 语言插桩仅限于某些特定库。 | 可用 Go 插桩项 | 支持情况 | |--------------------------------------|----------| | 标准 Go `net/http` | ✅ | | [Gorilla Mux](https://github.com/gorilla/mux) | ✅ | | [Gin](https://gin-gonic.com/) | ✅ | | [gRPC-Go](https://github.com/grpc/grpc-go) | ✅ | | [Go x/net/http2](https://golang.org/x/net/http2) | ✅ | | [Go-Redis v9](github.com/redis/go-redis) | ✅ | | [Sarama Kafka](github.com/IBM/sarama) | ✅ | | [kafka-Go](https://github.com/segmentio/kafka-go) | ✅ | HTTPS 插桩仅限于 Go 程序和使用 libssl3 的库/语言。 ## Similarly, for these headings, if they are standalone names, I might keep them in English and not add any Chinese. But the task says "translate to Simplified Chinese", so perhaps I need to provide the Chinese version of the name, if it exists. 您可以直接使用 `deployments/` 文件夹中的 Kubernetes 描述符。 1. 提供您的 Grafana 凭证。使用以下 [K8s Secret 模板](deployments/01-grafana-credentials.template.yml) 来设置 Mimir 和 Tempo 的端点、用户名和 API 密钥： ``` $ cp deployments/01-grafana-credentials.template.yml 01-grafana-credentials.yml $ # 编辑字段 $ vim 01-grafana-credentials.yml $ kubectl apply -f 01-grafana-credentials.yml ``` 2. 部署 Grafana Agent： ``` kubectl apply -f deployments/02-grafana-agent.yml ``` 3. 部署一个带有自动插桩器作为 sidecar 的演示应用。您可以使用 [deployments/03-instrumented-app.yml](./deployments/03-instrumented-app.yml) 文件中的博客示例。 ``` $ kubectl apply -f ./deployments/03-instrumented-app.yml $ kubectl port-forward service/goblog 8443:8443 ``` 您应该能够在 Grafana 面板中查询跟踪和指标。 ## 从头构建 Beyla ### 开发环境要求 #### 最低要求 - go 1.25 - docker - GNU make #### 可选要求 - llvm >= 19 - clang >= 19 #### 常见 `Makefile` 目标 Beyla 的 `Makefile` 提供了几个特定用途的构建目标。最常用的是： - `prereqs` - 安装构建先决条件 - `docker-generate` - 重新生成 eBPF 二进制文件（*首选方法*） - `generate` - 重新生成 eBPF 二进制文件[^1] - `compile` - 编译 `beyla` 二进制文件（但不自动重新生成 eBPF 二进制文件） - `dev` - 等同于 `make prereqs && make docker-generate && make compile` - `test` - 运行单元测试 - `integration-test` - 运行集成测试 - 可能需要 `sudo` 权限 - `clang-format` - 格式化 C (eBPF) 源代码[^1] - `vendor-obi` - 在子模块中下载所有 OpenTelemetry-eBPF-Instrumentation (OBI) 依赖项，构建 BPF 目标，并将其 vendor 化。 [^1]: 需要 llvm/clang #### 快速开始 ``` $ git clone https://github.com/grafana/beyla.git $ cd beyla/ $ make dev ``` 如上一节所述，`make dev` 负责设置构建先决条件，包括部署 `clang-format` 预提交钩子。 编译成功后，可在 `bin/` 子目录中找到二进制文件。 #### 管理对 opentelemetry-ebpf-instrumentation 的代码依赖 Beyla 将 [opentelemetry-ebpf-instrumentation](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation) (OBI) 项目的部分代码 vendor 化。 该代码作为 Git 子模块（名为 `obi-src`）包含在 Beyla 代码库的 `.obi-src` 文件夹中。 `.obi-src` 的内容用于构建 BPF 依赖项，并在第二步中将其 vendor 化到 `vendor/` 目录中。 通常，您只需运行 `make vendor-obi` 即可获取子模块数据、编译 BPF 目标并在本地进行 vendor 化。 `.obi-src` 文件夹被固定在 OBI Git 历史记录的特定版本。如果您在上游 [opentelemetry-ebpf-instrumentation](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation) 仓库中进行了更改，并希望将 `.obi-src` 更新到最新内容，需要从 Beyla 项目文件夹运行： ``` git submodule update --checkout --remote git add . ``` （`git add .` 非常重要，否则在尝试重新编译代码时，`obi-src` 子模块可能会恢复到其原始状态）。 #### 使用 opentelemetry-ebpf-instrumentation 的本地开发分支进行开发 暂时转到 `go.mod`，将第一个 `replace` 指令替换为您的本地 OBI 文件夹。例如： ``` -replace go.opentelemetry.io/obi => ./.obi-src +replace go.opentelemetry.io/obi => ../opentelemetry-ebpf-instrumentation ``` 使用 `make dev-image-build` 构建 docker 镜像。 ⚠️ 在将更改推送到我们的 GitHub 仓库之前，不要忘记恢复 `go.mod` 中的 `replace` 指令！ #### 格式化和检查代码 Beyla 使用检查工具来强制执行我们的编码风格和最佳实践： - `golangci-lint` 用于 Go 代码 - `clang-format` 用于格式化 C 代码 - `clang-tidy` 用于 C 代码的静态分析 所有这些都在拉取请求时作为 Beyla GitHub 工作流程的一部分被强制执行。此外，您可以手动调用检查工具： - `make lint` 对 Go 代码调用 `golangci-lint` - `make clang-tidy` 对 C/eBPF 代码调用 `clang-tidy` `clang-format` 作为 `pre-commit` git 钩子自动调用，您可以使用 `Makefile` 的 `clang-format` 目标直接运行它。 #### 运行虚拟机测试 除了 `test` 和 `integration-test` 的 `Makefile` 目标外，Beyla 还会在 QEMU 虚拟机上运行选定的测试，以便能够测试不同的内核版本。这些测试也是我们 GitHub 工作流程的一部分，但也可以使用以下命令手动运行： ``` $ sudo make -C internal/testgenerated/vm KERNEL_VER=... ``` 其中 `KERNEL_VER` 是位于 `internal/testgenerated/vm/kernels` 中的受支持内核版本之一。例如，要针对内核版本 5.15.152 运行测试，只需执行： ``` $ sudo make -C internal/testgenerated/vm KERNEL_VER=5.15.152 ``` ## 致谢 部分代码取自：https://github.com/open-telemetry/opentelemetry-go-instrumentation

标签：Docker镜像, eBPF监控工具, EVTX分析, GET参数, Grafana Beyla, gRPC监控, HTTP监控, IPv6支持, OpenTelemetry, OpenTelemetry集成, RED指标, Web应用性能, 分布式跟踪, 可观测性平台, 子域名突变, 安全渗透, 应用性能管理, 微服务可观测性, 日志审计, 用户代理, 监控工具, 网络指标收集, 自动检测, 自定义请求头, 请求拦截, 零代码监控, 零侵入性监控