OBI - OpenTelemetry eBPF 零代码接入指南

本文档提供 OpenTelemetry eBPF Instrumentation (OBI) 的完整接入指南，这是一个基于 eBPF 技术的零代码自动埋点工具，支持多种编程语言的应用程序监控。

目录

• 什么是 OBI
• 核心特性
• 与传统方式对比
• 适用场景
• 系统要求
• 兼容性
• 限制与注意事项
• 快速开始
• 详细配置
• 网络可观测性
• 分布式追踪
• 安全性
• 高级主题
• 实战示例
• 最佳实践
• 故障排查
• 下一步
• 参考资源

什么是 OBI

OpenTelemetry eBPF Instrumentation (OBI) 是一个革命性的自动埋点工具，它使用 eBPF (extended Berkeley Packet Filter) 技术实现零侵入的应用程序监控。与传统的 APM 解决方案不同，OBI 可以在不修改应用代码、不重启服务、不安装语言 SDK 的情况下，自动捕获分布式追踪数据和性能指标。

eBPF 技术简介

eBPF 是一项革命性的 Linux 内核技术，允许在内核空间运行沙箱化的程序，无需修改内核源码或加载内核模块。OBI 利用 eBPF 的强大能力：

• 内核级监控：在操作系统内核层面拦截和分析应用程序的网络调用、系统调用
• 零开销埋点：eBPF 程序经过 JIT 编译，执行效率接近原生代码
• 安全隔离：eBPF 程序在内核验证器的保护下运行，确保系统安全性
• 动态加载：无需重启应用或修改代码，实时启用和禁用监控

OBI 的工作原理

OBI 通过以下方式实现自动埋点：

1. 进程发现：自动扫描系统中运行的进程，识别需要监控的服务
2. eBPF 探针注入：将 eBPF 程序注入到内核，拦截网络系统调用（如 read、write、sendto、recvfrom）
3. 协议解析：在内核空间解析 HTTP、gRPC 等应用层协议
4. Span 生成：根据请求/响应自动生成分布式追踪 Span
5. 上下文传播：自动提取和注入 Trace Context（W3C TraceContext、B3 等）
6. 数据导出：通过 OTLP 协议将 Traces 和 Metrics 发送到后端

┌─────────────────────────────────────────────────────────────┐
│                    应用程序（无需修改）                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Go App  │  │Java App  │  │Python App│  │ Node.js  │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
└───────┼─────────────┼──────────────┼─────────────┼─────────┘
        │             │              │             │
        └─────────────┴──────────────┴─────────────┘
                      │ 网络系统调用
        ┌─────────────▼──────────────────────────┐
        │         Linux 内核 + eBPF               │
        │  ┌────────────────────────────────┐    │
        │  │   OBI eBPF 探针                │    │
        │  │  - HTTP/gRPC 协议解析          │    │
        │  │  - Trace Context 传播          │    │
        │  │  - 数据库查询捕获              │    │
        │  │  - TLS/SSL 流量拦截            │    │
        │  └────────────────────────────────┘    │
        └─────────────┬──────────────────────────┘
                      │ OTLP
        ┌─────────────▼──────────────────────────┐
        │         Uptrace / Collector            │
        │   uptrace-grpc.yodao.cn:4317           │
        └────────────────────────────────────────┘

核心特性

1. 广泛的语言支持

OBI 支持 9 种主流编程语言，无需安装任何语言特定的 SDK：

2. 零代码接入

• ✅ 无需修改应用代码：不需要添加任何埋点代码
• ✅ 无需安装 SDK：不需要安装语言特定的 OpenTelemetry SDK
• ✅ 无需重启服务：可以在运行时动态启用监控
• ✅ 无需容器重构：可以监控现有容器，无需重新构建镜像

3. 高效的性能

• 低 CPU 开销：eBPF 程序在内核空间运行，经过 JIT 编译，开销 < 1%
• 低内存占用：典型场景下内存占用 < 100MB
• 智能采样：支持多种采样策略，降低数据量和成本

4. 分布式追踪

• 自动 Span 生成：为每个 HTTP/gRPC 请求自动创建 Span
• 上下文传播：自动提取和注入 W3C TraceContext、B3、Jaeger 等传播协议
• 服务拓扑：自动构建服务依赖关系图
• 调用链路：完整的端到端请求链路追踪

5. Kubernetes 原生支持

• DaemonSet 部署：一次部署，监控整个集群
• 自动服务发现：自动发现 Pod 和容器中的服务
• Pod 注解配置：支持通过 Annotation 配置监控策略
• Namespace 隔离：支持按命名空间过滤和监控

6. TLS/SSL 可见性

• 加密流量监控：无需解密即可监控 HTTPS、gRPC over TLS 流量
• 零配置：自动识别 TLS 连接，无需提供证书或密钥
• 协议支持：支持 TLS 1.2、TLS 1.3

7. 网络可观测性

• 点对点网络指标：监控服务之间的网络流量、延迟、错误率
• 跨可用区流量分析：识别和优化跨 AZ 流量，降低云成本
• 网络拓扑：可视化服务之间的网络连接

8. 数据库追踪

• 自动数据库查询捕获：捕获 SQL 查询、Redis 命令等
• 慢查询识别：自动标记超过阈值的数据库操作
• 连接池监控：监控数据库连接数、连接时间

9. 协议支持

• HTTP/HTTPS：HTTP/1.0、HTTP/1.1、HTTP/2
• gRPC：gRPC、gRPC-Web
• Database：MySQL、PostgreSQL、Redis（通过协议解析）

10. 低基数指标

• Prometheus 兼容：导出符合 Prometheus 命名规范的指标
• 基数控制：智能标签聚合，避免基数爆炸
• RED 指标：Rate（请求速率）、Errors（错误率）、Duration（延迟）

与传统方式对比

建议：

• 快速启动阶段：使用 OBI 快速实现全链路追踪，无需修改代码
• 生产环境：结合使用 OBI + 语言 Agent，OBI 提供基础监控，Agent 提供精细化监控
• 关键业务：使用 SDK 手动埋点，实现自定义业务指标和深度分析

适用场景

1. 快速启动分布式追踪

场景：您的团队刚开始接入 OpenTelemetry，需要快速看到效果。

解决方案：

• 使用 OBI 在 5 分钟内启动全链路追踪
• 无需学习各语言的 SDK 使用方法
• 无需修改现有代码

示例：

# 一行命令启动监控
docker run -d --name obi --privileged --pid host \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80 \
  -e OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project \
  grafana/beyla:latest

2. 编译语言的自动埋点

场景：您的应用使用 Go、Rust、C++ 等编译语言，手动埋点需要修改代码、重新编译、重新部署。

解决方案：

• OBI 可以在不修改代码的情况下监控编译语言应用
• 自动捕获 HTTP、gRPC 调用
• 无需重新编译和部署

适用语言：

• Go（goroutine 友好）
• Rust（零成本抽象）
• C/C++（遗留系统）

3. 遗留系统的可观测性改造

场景：您有大量遗留系统，修改代码成本高、风险大。

解决方案：

• OBI 可以监控任何运行在 Linux 上的应用，无论多老
• 无需修改代码，降低改造风险
• 快速定位性能瓶颈

示例：

• 10 年前的 Java 单体应用
• C++ 编写的高性能服务
• Python 2.7 的遗留系统

4. Kubernetes 环境的无配置监控

场景：您有数百个微服务运行在 Kubernetes 集群中，逐个配置监控太麻烦。

解决方案：

• 使用 DaemonSet 部署 OBI，自动监控所有 Pod
• 自动服务发现，无需手动配置
• 支持通过 Pod Annotation 自定义监控策略

示例：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: obi
spec:
  template:
    spec:
      hostPID: true
      hostNetwork: true
      containers:
      - name: obi
        image: grafana/beyla:latest
        securityContext:
          privileged: true

5. 混合语言微服务架构

场景：您的系统使用多种编程语言（Go + Java + Python + Node.js），每种语言都需要单独配置 Agent。

解决方案：

• OBI 提供统一的监控方案，一次部署支持所有语言
• 自动关联不同语言服务之间的调用链路
• 简化运维复杂度

6. 临时性能分析

场景：生产环境出现性能问题，需要快速定位，但没有提前部署监控。

解决方案：

• 动态启用 OBI，无需重启服务
• 快速捕获性能数据
• 问题解决后，随时禁用

7. 成本优化

场景：跨可用区（AZ）流量产生高额云成本。

解决方案：

• 使用 OBI 的网络可观测性功能
• 识别跨 AZ 流量模式
• 优化服务部署，降低云成本

系统要求

OBI 对运行环境有一定要求，主要与 Linux 内核版本和 eBPF 支持相关。

最低系统要求

内核版本说明

标准 Linux 发行版：

• 需要 Linux 内核 5.8 或更高版本
• 支持的内核特性：
  • BPF Type Format (BTF)
  • BPF CO-RE (Compile Once, Run Everywhere)
  • BPF Ring Buffer

Red Hat 系列（RHEL、CentOS、Rocky、AlmaLinux）：

• 支持 内核 4.18（backport 了 eBPF 相关补丁）
• RHEL 8、CentOS 8、Rocky Linux 8、AlmaLinux 8 及以上

检查内核版本

# 查看内核版本
uname -r

# 检查 eBPF 支持
ls /sys/kernel/debug/tracing/

# 检查 BTF 支持
ls /sys/kernel/btf/vmlinux

Go 应用特殊要求

如果您要监控 Go 应用，需要注意：

• Go 版本：1.17 或更高
• 版本支持策略：OBI 支持当前稳定版本向后 3 个主版本
  • 例如：当前 Go 最新版本是 1.21，则支持 1.21、1.20、1.19、1.18
• 编译要求：Go 应用需要包含调试信息（默认包含）

兼容性

支持的 Linux 发行版

OBI 已在以下 Linux 发行版上测试通过：

Ubuntu

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 21.04 (Hirsute Hippo)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Ubuntu 23.04 (Lunar Lobster)
• Ubuntu 24.04 LTS (Noble Numbat)

Red Hat Enterprise Linux (RHEL)

• RHEL 8.x
• RHEL 9.x

CentOS

• CentOS 7 (内核需升级到 5.8+)
• CentOS 8
• CentOS 9

AlmaLinux

• AlmaLinux 8
• AlmaLinux 9

Rocky Linux

• Rocky Linux 8
• Rocky Linux 9

Debian

• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

openSUSE

• openSUSE Leap 15.3
• openSUSE Leap 15.4
• openSUSE Leap 15.5

SUSE Linux Enterprise Server (SLES)

• SLES 15 SP4
• SLES 15 SP5

Kubernetes 支持

OBI 支持在 Kubernetes 环境中部署：

• Kubernetes 版本：1.20+
• 容器运行时：
  • containerd
  • Docker
  • CRI-O
• 部署方式：
  • DaemonSet（推荐）
  • Sidecar（特定场景）

云平台支持

OBI 可以运行在以下云平台：

• AWS：EC2、EKS
• Azure：VM、AKS
• Google Cloud：GCE、GKE
• 阿里云：ECS、ACK
• 私有云：OpenStack、VMware

限制与注意事项

虽然 OBI 提供了强大的零代码监控能力，但也存在一些限制：

功能限制

1. 监控粒度

• ✅ 支持：HTTP/gRPC 事务级监控、数据库查询
• ❌ 不支持：方法级、函数级监控
• ⚠️ 影响：无法监控业务逻辑内部的性能瓶颈

解决方案：对于需要方法级监控的关键服务，结合使用语言 Agent。

2. 自定义属性

• ✅ 支持：HTTP headers、gRPC metadata 中的标准属性
• ❌ 不支持：自定义业务属性（如用户 ID、订单 ID）
• ⚠️ 影响：无法根据业务维度分析性能

解决方案：将业务属性编码在 HTTP headers 中，或使用 SDK 手动埋点补充。

3. 业务指标

• ❌ 不支持：自定义业务指标（如订单金额、支付成功率）
• ⚠️ 影响：只能监控技术指标（延迟、错误率），无法监控业务指标

解决方案：使用 OpenTelemetry SDK 添加自定义 Metrics。

4. 日志关联

• ⚠️ 有限支持：可以捕获 HTTP 请求日志，但无法关联应用日志
• ❌ 不支持：自动将 Trace ID 注入应用日志

解决方案：使用日志库的 OpenTelemetry 集成（如 logrus、zap）。

权限要求

OBI 需要较高的系统权限才能运行：

Docker 运行

• 需要 --privileged 标志或以下 Capabilities：
  • CAP_DAC_READ_SEARCH
  • CAP_SYS_PTRACE
  • CAP_PERFMON
  • CAP_BPF
  • CAP_CHECKPOINT_RESTORE
  • CAP_NET_ADMIN（仅网络监控功能）

Kubernetes 运行

• DaemonSet 需要：
  • hostPID: true
  • hostNetwork: true（可选，用于网络监控）
  • privileged: true 或特定 Capabilities

安全考虑：

• 在生产环境中，建议使用最小权限原则，仅授予必需的 Capabilities
• 详见安全性章节

性能考虑

虽然 OBI 的性能开销很低，但在极端场景下仍需注意：

• 高并发场景（QPS > 10,000）：
  • 建议启用采样（如 10% 采样率）
  • 监控 OBI 自身的 CPU 和内存使用
• 大量服务（100+ 个服务）：
  • 考虑使用服务过滤，只监控关键服务
  • 避免监控短生命周期进程（如 cron 作业）

Go 应用限制

• Go 版本：不支持 Go 1.16 及更早版本
• 版本支持窗口：仅支持当前版本向后 3 个主版本
• 调试信息：需要保留调试信息，不要使用 go build -ldflags="-s -w"

协议支持限制

• HTTP/2 服务端推送：不支持
• WebSocket：有限支持（仅连接建立）
• 自定义协议：不支持

建议

1. 混合使用：OBI + 语言 Agent + SDK 手动埋点

   • OBI：快速启动、覆盖所有服务
   • Agent：关键服务的精细化监控
   • SDK：自定义业务指标

2. 分阶段实施：

   • 第一阶段：使用 OBI 快速实现全链路追踪
   • 第二阶段：对关键服务添加语言 Agent
   • 第三阶段：对核心业务逻辑使用 SDK 手动埋点

3. 评估场景：

   • 如果只需要 HTTP/gRPC 事务级监控，OBI 完全够用
   • 如果需要业务指标、方法级监控，必须结合其他方案

快速开始

本节将指导您在 5 分钟内启动 OBI 并开始监控您的应用程序。

前提条件

• Linux 系统（内核 5.8+ 或 RHEL 4.18+）
• Docker 或 Kubernetes（根据部署方式）
• 有效的 Uptrace DSN（从 内部平台 获取）

方式 1：Docker 部署（推荐用于快速测试）

这是最快的启动方式，适合单机测试和开发环境。

步骤 1：运行 OBI 容器

docker run -d \
  --name obi \
  --privileged \
  --pid host \
  --network host \
  -e OTEL_SERVICE_NAME=my-service \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80 \
  -e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
  -e OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317" \
  -e BEYLA_OPEN_PORT=8080,8443,3000 \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  grafana/beyla:latest

参数说明：

• --privileged：授予容器特权，允许访问 eBPF
• --pid host：使用主机 PID 命名空间，以便监控主机上的进程
• --network host：使用主机网络（可选，推荐）
• OTEL_SERVICE_NAME：服务名称（如果不设置，会自动从进程名提取）
• OTEL_EXPORTER_OTLP_ENDPOINT：Uptrace 平台地址
• OTEL_EXPORTER_OTLP_HEADERS：包含 DSN 的认证信息
• BEYLA_OPEN_PORT：要监控的端口列表（逗号分隔）
• -v /sys/kernel/debug：挂载内核调试文件系统
• -v /var/run/docker.sock：允许监控其他 Docker 容器

步骤 2：验证 OBI 运行状态

# 查看 OBI 日志
docker logs -f obi

# 应该看到类似输出：
# time=2024-01-01T00:00:00.000Z level=INFO msg="Starting OBI"
# time=2024-01-01T00:00:01.000Z level=INFO msg="Discovered service" service=my-app port=8080 pid=12345
# time=2024-01-01T00:00:02.000Z level=INFO msg="eBPF programs loaded successfully"

步骤 3：生成测试流量

# 向您的应用发送请求
curl http://localhost:8080/api/health

# 或使用 ab 进行压测
ab -n 1000 -c 10 http://localhost:8080/api/health

步骤 4：在 Uptrace 查看数据

1. 访问 Uptrace 内部平台
2. 选择您的项目
3. 进入 "Traces" 页面
4. 应该能看到刚才生成的请求追踪数据

方式 2：Docker Compose 部署

适合多容器应用的本地开发和测试。

创建 docker-compose.yml

version: '3.8'

services:
  # 您的应用服务
  my-app:
    image: my-app:latest
    ports:
      - "8080:8080"
    environment:
      - APP_ENV=production

  # OBI 监控服务
  obi:
    image: grafana/beyla:latest
    pid: "host"
    network_mode: "host"
    privileged: true
    environment:
      # 基础配置
      OTEL_SERVICE_NAME: my-app
      OTEL_EXPORTER_OTLP_ENDPOINT: http://uptrace-grpc.yodao.cn:80
      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
      OTEL_EXPORTER_OTLP_HEADERS: "uptrace-dsn=http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"
      
      # 服务发现配置
      BEYLA_OPEN_PORT: "8080"  # 监控 8080 端口的服务
      
      # 采样配置（可选）
      BEYLA_TRACE_SAMPLE_RATE: "1.0"  # 100% 采样
      
      # 日志级别
      BEYLA_LOG_LEVEL: "INFO"
    volumes:
      - /sys/kernel/debug:/sys/kernel/debug:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

启动服务

docker-compose up -d

# 查看日志
docker-compose logs -f obi

方式 3：Kubernetes 部署（推荐用于生产环境）

在 Kubernetes 中使用 DaemonSet 部署 OBI，可以自动监控整个集群中的所有服务。

步骤 1：创建 Secret（存储 DSN）

kubectl create secret generic obi-credentials \
  --from-literal=dsn="http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317" \
  -n monitoring

步骤 2：创建 ConfigMap（配置 OBI）

# obi-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: obi-config
  namespace: monitoring
data:
  beyla.yaml: |
    # OTLP Exporter 配置
    otel_exporter:
      endpoint: http://uptrace-grpc.yodao.cn:80
      protocol: http/protobuf
      insecure: true
    
    # 服务发现配置
    discovery:
      # 自动发现所有监听端口的服务
      services:
        - open_ports: 80,443,8080,8443,3000,4000,5000,8000,9000
    
    # 采样配置
    traces:
      sample_rate: 0.1  # 10% 采样率
    
    # 日志级别
    log_level: INFO

kubectl apply -f obi-configmap.yaml

步骤 3：创建 DaemonSet

# obi-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: obi
  namespace: monitoring
  labels:
    app: obi
spec:
  selector:
    matchLabels:
      app: obi
  template:
    metadata:
      labels:
        app: obi
    spec:
      hostPID: true
      hostNetwork: true
      serviceAccountName: obi
      containers:
      - name: obi
        image: grafana/beyla:latest
        securityContext:
          privileged: true
          runAsUser: 0
        env:
        # 从 Secret 读取 DSN
        - name: OTEL_EXPORTER_OTLP_HEADERS
          valueFrom:
            secretKeyRef:
              name: obi-credentials
              key: dsn
        # 从 ConfigMap 读取配置文件路径
        - name: BEYLA_CONFIG_PATH
          value: /etc/beyla/beyla.yaml
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
          requests:
            cpu: 100m
            memory: 256Mi
        volumeMounts:
        - name: config
          mountPath: /etc/beyla
          readOnly: true
        - name: sys-kernel-debug
          mountPath: /sys/kernel/debug
          readOnly: true
        - name: cgroup
          mountPath: /sys/fs/cgroup
          readOnly: true
      volumes:
      - name: config
        configMap:
          name: obi-config
      - name: sys-kernel-debug
        hostPath:
          path: /sys/kernel/debug
      - name: cgroup
        hostPath:
          path: /sys/fs/cgroup

步骤 4：创建 ServiceAccount 和 RBAC（可选，用于高级功能）

# obi-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: obi
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: obi
rules:
- apiGroups: [""]
  resources: ["pods", "nodes"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: obi
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: obi
subjects:
- kind: ServiceAccount
  name: obi
  namespace: monitoring

步骤 5：部署

# 创建 namespace
kubectl create namespace monitoring

# 部署 RBAC
kubectl apply -f obi-rbac.yaml

# 部署 DaemonSet
kubectl apply -f obi-daemonset.yaml

# 查看部署状态
kubectl get ds -n monitoring
kubectl get pods -n monitoring -l app=obi

# 查看日志
kubectl logs -n monitoring -l app=obi --tail=100 -f

方式 4：Kubernetes Helm 部署（最简单）

使用 Helm Chart 可以一键部署 OBI。

步骤 1：添加 Helm Repository

# 添加 Grafana Helm Repo（Beyla/OBI）
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

步骤 2：创建 values.yaml

# obi-values.yaml
# DSN 配置
env:
  OTEL_EXPORTER_OTLP_ENDPOINT: "http://uptrace-grpc.yodao.cn:80"
  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf"
  OTEL_EXPORTER_OTLP_HEADERS: "uptrace-dsn=http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"
  BEYLA_LOG_LEVEL: "INFO"
  BEYLA_OPEN_PORT: "80,443,8080,8443,3000,4000,5000"
  BEYLA_TRACE_SAMPLE_RATE: "0.1"

# 资源限制
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 256Mi

# 安全上下文
securityContext:
  privileged: true
  runAsUser: 0

# 使用主机 PID 和网络
hostPID: true
hostNetwork: true

步骤 3：安装

helm install obi grafana/beyla \
  --namespace monitoring \
  --create-namespace \
  --values obi-values.yaml

步骤 4：验证

# 查看部署状态
helm status obi -n monitoring

# 查看 Pods
kubectl get pods -n monitoring -l app.kubernetes.io/name=beyla

# 查看日志
kubectl logs -n monitoring -l app.kubernetes.io/name=beyla --tail=100 -f

方式 5：Standalone 部署（二进制）

适合在虚拟机或物理机上直接运行，无需容器。

步骤 1：下载 OBI 二进制文件

# 下载最新版本（Linux x86_64）
curl -L -o beyla.tar.gz \
  https://github.com/grafana/beyla/releases/latest/download/beyla-linux-amd64.tar.gz

# 解压
tar -xzf beyla.tar.gz

# 移动到系统路径
sudo mv beyla /usr/local/bin/
sudo chmod +x /usr/local/bin/beyla

# 验证安装
beyla --version

步骤 2：创建配置文件

sudo mkdir -p /etc/beyla
sudo vi /etc/beyla/config.yaml

# /etc/beyla/config.yaml
# OTLP Exporter 配置
otel_exporter:
  endpoint: http://uptrace-grpc.yodao.cn:80
  protocol: http/protobuf
  insecure: true
  headers:
    uptrace-dsn: "http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"

# 服务发现
discovery:
  services:
    - open_ports: 8080,8443,3000
    - exe_path: "/usr/local/bin/myapp"  # 或指定可执行文件路径

# 采样配置
traces:
  sample_rate: 0.1

# 日志配置
log_level: INFO

步骤 3：创建 systemd 服务

sudo vi /etc/systemd/system/beyla.service

[Unit]
Description=OpenTelemetry eBPF Instrumentation (OBI/Beyla)
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/beyla --config /etc/beyla/config.yaml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# 所需的 Capabilities
AmbientCapabilities=CAP_DAC_READ_SEARCH CAP_SYS_PTRACE CAP_PERFMON CAP_BPF CAP_CHECKPOINT_RESTORE
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

步骤 4：启动服务

# 重新加载 systemd
sudo systemctl daemon-reload

# 启动 OBI
sudo systemctl start beyla

# 设置开机自启
sudo systemctl enable beyla

# 查看状态
sudo systemctl status beyla

# 查看日志
sudo journalctl -u beyla -f

验证监控数据

无论使用哪种部署方式，部署完成后都应该：

1. 检查 OBI 日志

确认 OBI 已成功发现服务并加载 eBPF 程序：

level=INFO msg="Discovered service" service=my-app port=8080 pid=12345
level=INFO msg="eBPF programs loaded successfully"
level=INFO msg="Started exporting traces" endpoint=http://uptrace-grpc.yodao.cn:80

2. 生成测试流量

# 向您的应用发送请求
for i in {1..100}; do
  curl http://localhost:8080/api/endpoint
  sleep 0.1
done

3. 在 Uptrace 平台查看数据

1. 访问 Uptrace 内部平台
2. 选择您的项目
3. 进入 "Traces" 页面
4. 筛选服务名称，查看 Trace 数据
5. 进入 "Metrics" 页面，查看 HTTP 请求指标

4. 验证 Trace Context 传播

# 使用 curl 发送请求，包含 Trace ID
curl -H "traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" \
  http://localhost:8080/api/endpoint

# 在 Uptrace 中搜索 Trace ID: 0af7651916cd43dd8448eb211c80319c
# 应该能看到完整的调用链路

详细配置

OBI 提供了丰富的配置选项，可以通过环境变量或 YAML 配置文件进行配置。

配置方式

方式 1：环境变量（推荐用于 Docker/Kubernetes）

docker run -d \
  -e OTEL_SERVICE_NAME=my-service \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80 \
  ...
  grafana/beyla:latest

方式 2：YAML 配置文件（推荐用于 Standalone）

beyla --config /etc/beyla/config.yaml

或通过环境变量指定配置文件：

export BEYLA_CONFIG_PATH=/etc/beyla/config.yaml
beyla

导出配置

配置如何将 Traces 和 Metrics 导出到 Uptrace 平台。

环境变量方式

# OTLP 端点地址（HTTP 协议）
export OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80

# 协议类型
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf  # 或 grpc

# 认证信息（DSN）
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"

# 超时时间（秒）
export OTEL_EXPORTER_OTLP_TIMEOUT=10

# 压缩（可选）
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

YAML 配置方式

otel_exporter:
  # 端点地址
  endpoint: http://uptrace-grpc.yodao.cn:80
  
  # 协议类型：http/protobuf 或 grpc
  protocol: http/protobuf
  
  # 是否允许不安全连接（HTTP）
  insecure: true
  
  # HTTP 请求头（包含 DSN）
  headers:
    uptrace-dsn: "http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"
  
  # 超时时间
  timeout: 10s
  
  # 批量导出配置
  batch:
    max_export_batch_size: 512
    schedule_delay: 5s
    max_queue_size: 2048

gRPC 协议配置

如果您想使用 gRPC 协议（性能更好）：

otel_exporter:
  endpoint: uptrace-grpc.yodao.cn:4317
  protocol: grpc
  insecure: false  # gRPC 默认使用 TLS
  headers:
    uptrace-dsn: "http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"

全局属性配置

配置服务的基础属性和资源标签。

环境变量方式

# 服务名称（必需）
export OTEL_SERVICE_NAME=my-service

# 服务版本
export OTEL_SERVICE_VERSION=1.0.0

# 资源属性（键值对，逗号分隔）
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.namespace=backend,service.instance.id=instance-001"

# Beyla 特有的命名空间
export BEYLA_SERVICE_NAMESPACE=backend

YAML 配置方式

# 服务属性
attributes:
  # 服务名称（如果不设置，会从进程名自动提取）
  service.name: my-service
  service.version: 1.0.0
  service.namespace: backend
  service.instance.id: instance-001
  
  # 部署环境
  deployment.environment: production
  
  # 自定义标签
  team: platform
  owner: john.doe@company.com

服务发现配置

配置 OBI 如何发现和选择要监控的服务。

按端口发现

环境变量：

# 监控指定端口的服务（逗号分隔）
export BEYLA_OPEN_PORT=8080,8443,3000,4000,5000

# 监控端口范围
export BEYLA_OPEN_PORT=8000-9000

YAML 配置：

discovery:
  services:
    # 监控指定端口
    - open_ports: 8080,8443,3000
    
    # 监控端口范围
    - open_ports: 8000-9000

按进程名发现

环境变量：

# 监控指定进程名的服务（正则表达式）
export BEYLA_EXECUTABLE_NAME="^(my-app|api-server)$"

YAML 配置：

discovery:
  services:
    # 监控特定可执行文件路径
    - exe_path: /usr/local/bin/my-app
    
    # 监控进程名（正则表达式）
    - exe_name_regex: "^(my-app|api-server)$"

按容器/Pod 发现（Kubernetes）

YAML 配置：

discovery:
  services:
    # 监控特定命名空间的 Pod
    - k8s_namespace: default
    
    # 监控带有特定标签的 Pod
    - k8s_pod_labels:
        app: my-app
        tier: backend
    
    # 监控特定 Pod 名称
    - k8s_pod_name: my-app-pod-12345

混合条件

YAML 配置：

discovery:
  services:
    # 监控 default 命名空间下监听 8080 端口的服务
    - k8s_namespace: default
      open_ports: 8080
      
    # 监控特定可执行文件且监听 443 端口
    - exe_path: /usr/bin/nginx
      open_ports: 443

排除规则

YAML 配置：

discovery:
  # 要监控的服务
  services:
    - open_ports: 8000-9000
  
  # 排除特定进程
  exclude:
    # 排除 Kubernetes 系统组件
    - k8s_namespace: kube-system
    
    # 排除短生命周期进程
    - exe_name_regex: "^(cron|systemd)$"

数据过滤配置

配置哪些 HTTP 请求需要被记录、采样。

HTTP 路径过滤

环境变量：

# 排除健康检查端点
export BEYLA_HTTP_PATH_EXCLUSIONS="/health,/metrics,/ping"

YAML 配置：

routes:
  # 忽略的路径（不记录 Trace）
  ignore:
    - path: /health
    - path: /metrics
    - path: /ping
    - path: /favicon.ico
  
  # 模式匹配（支持通配符）
  ignore_patterns:
    - /api/internal/*
    - /debug/*
    - /_next/static/*

HTTP 方法过滤

routes:
  ignore:
    # 忽略 OPTIONS 请求（CORS 预检）
    - method: OPTIONS

状态码过滤

routes:
  # 只记录错误请求（4xx, 5xx）
  ignore_success: true
  
  # 或自定义状态码过滤
  ignore:
    - status_code: 200
    - status_code: 204
    - status_code: 304

User-Agent 过滤

routes:
  ignore:
    # 忽略监控探针
    - user_agent: "^(Prometheus|kube-probe)/"

采样配置

配置 Trace 采样策略，降低数据量和成本。

全局采样率

环境变量：

# 设置采样率（0.0 - 1.0）
export BEYLA_TRACE_SAMPLE_RATE=0.1  # 10% 采样

YAML 配置：

traces:
  # 全局采样率（0.0 - 1.0）
  sample_rate: 0.1  # 10% 采样

基于路径的采样

traces:
  # 默认采样率
  sample_rate: 0.1
  
  # 路径特定采样率
  sampling_rules:
    # 关键业务接口 100% 采样
    - path: /api/payment/*
      sample_rate: 1.0
    
    # 查询接口低采样
    - path: /api/query/*
      sample_rate: 0.01
    
    # 健康检查不采样
    - path: /health
      sample_rate: 0.0

基于状态码的采样

traces:
  sample_rate: 0.1
  
  sampling_rules:
    # 错误请求 100% 采样
    - status_code_range: [400, 599]
      sample_rate: 1.0
    
    # 成功请求低采样
    - status_code_range: [200, 299]
      sample_rate: 0.05

基于延迟的采样

traces:
  sample_rate: 0.1
  
  sampling_rules:
    # 慢请求 100% 采样
    - duration_ms: ">500"
      sample_rate: 1.0

指标属性配置

配置导出的 Metrics 包含哪些标签。

YAML 配置：

metrics:
  # 启用 Metrics 导出
  enable: true
  
  # Metrics 导出间隔
  interval: 60s
  
  # 包含的标签
  features:
    - http.method
    - http.status_code
    - http.route
    - service.name
    - service.namespace
  
  # 排除高基数标签
  exclude:
    - http.url  # 完整 URL 基数太高
    - http.target  # 完整路径基数太高
  
  # 路径聚合（降低基数）
  route_patterns:
    - pattern: "/api/users/:id"
      name: "/api/users/{id}"
    
    - pattern: "/api/orders/:order_id/items/:item_id"
      name: "/api/orders/{order_id}/items/{item_id}"

性能调优配置

配置 OBI 自身的性能参数。

YAML 配置：

# eBPF 配置
ebpf:
  # eBPF Map 大小（影响可同时追踪的请求数）
  track_request_headers: true
  
  # 环形缓冲区大小（字节）
  ring_buffer_size: 65536
  
  # 批量处理大小
  batch_size: 128

# 导出器配置
otel_exporter:
  # 批量导出配置
  batch:
    # 单批最大 Span 数
    max_export_batch_size: 512
    
    # 批量延迟时间
    schedule_delay: 5s
    
    # 队列大小
    max_queue_size: 2048
    
    # 导出超时
    export_timeout: 30s

# 日志配置
log_level: INFO  # DEBUG, INFO, WARN, ERROR

完整配置示例

综合所有配置项的完整示例：

# /etc/beyla/config.yaml

# 服务属性
attributes:
  service.name: my-production-service
  service.version: 2.1.0
  service.namespace: backend
  deployment.environment: production
  team: platform

# OTLP Exporter
otel_exporter:
  endpoint: http://uptrace-grpc.yodao.cn:80
  protocol: http/protobuf
  insecure: true
  headers:
    uptrace-dsn: "http://YOUR_TOKEN@uptrace-grpc.yodao.cn/YOUR_PROJECT?grpc=4317"
  timeout: 10s
  batch:
    max_export_batch_size: 512
    schedule_delay: 5s
    max_queue_size: 2048

# 服务发现
discovery:
  services:
    # 监控 backend 命名空间下的服务
    - k8s_namespace: backend
      open_ports: 8080,8443
    
    # 监控特定应用
    - exe_path: /usr/local/bin/api-server
  
  exclude:
    # 排除系统组件
    - k8s_namespace: kube-system
    - k8s_namespace: kube-public

# 路由过滤
routes:
  ignore:
    - path: /health
    - path: /metrics
    - path: /ping
    - method: OPTIONS
  
  ignore_patterns:
    - /_next/static/*
    - /static/*

# Traces 配置
traces:
  sample_rate: 0.1
  
  sampling_rules:
    # 关键接口 100% 采样
    - path: /api/payment/*
      sample_rate: 1.0
    
    # 错误请求 100% 采样
    - status_code_range: [400, 599]
      sample_rate: 1.0
    
    # 慢请求 100% 采样
    - duration_ms: ">1000"
      sample_rate: 1.0

# Metrics 配置
metrics:
  enable: true
  interval: 60s
  features:
    - http.method
    - http.status_code
    - http.route
  
  route_patterns:
    - pattern: "/api/users/:id"
      name: "/api/users/{id}"

# 性能调优
ebpf:
  ring_buffer_size: 65536
  batch_size: 128

# 日志级别
log_level: INFO

网络可观测性

OBI 不仅可以监控应用层的 HTTP/gRPC 流量，还可以监控网络层的流量，提供完整的网络可观测性。

网络监控功能

OBI 的网络可观测性功能包括：

• 点对点网络流量：监控服务之间的网络流量（字节数、包数）
• 网络延迟：TCP 连接建立时间、首字节时间
• 连接数统计：活跃连接数、新建连接速率
• 网络错误：连接失败、超时、重传
• 跨可用区流量识别：自动识别跨 AZ 流量，优化云成本

启用网络监控

环境变量方式

# 启用网络监控功能
export BEYLA_NETWORK_ENABLE=true

# 网络监控采样率
export BEYLA_NETWORK_SAMPLE_RATE=100  # 每秒采样 100 个连接

YAML 配置方式

network:
  # 启用网络监控
  enable: true
  
  # 采样配置
  sampling:
    # 每秒采样的连接数
    rate: 100
  
  # 监控的网络接口（默认所有）
  interfaces:
    - eth0
    - eth1
  
  # 监控的协议
  protocols:
    - TCP
    - UDP
  
  # 监控的方向
  direction:
    - ingress  # 入站
    - egress   # 出站

网络指标

OBI 导出以下网络指标：

1. 网络流量指标

# HELP network_traffic_bytes_total Total network traffic in bytes
# TYPE network_traffic_bytes_total counter
network_traffic_bytes_total{
  source_service="service-a",
  destination_service="service-b",
  protocol="TCP",
  direction="egress"
} 1048576

# HELP network_traffic_packets_total Total network packets
# TYPE network_traffic_packets_total counter
network_traffic_packets_total{
  source_service="service-a",
  destination_service="service-b",
  protocol="TCP"
} 1024

2. 连接数指标

# HELP network_connections_active Active network connections
# TYPE network_connections_active gauge
network_connections_active{
  source_service="service-a",
  destination_service="service-b"
} 42

# HELP network_connections_rate New connections per second
# TYPE network_connections_rate gauge
network_connections_rate{
  source_service="service-a",
  destination_service="service-b"
} 10.5

3. 网络延迟指标

# HELP network_connection_time_seconds TCP connection establishment time
# TYPE network_connection_time_seconds histogram
network_connection_time_seconds_bucket{
  source_service="service-a",
  destination_service="service-b",
  le="0.001"
} 50

# HELP network_ttfb_seconds Time to first byte
# TYPE network_ttfb_seconds histogram
network_ttfb_seconds_bucket{
  source_service="service-a",
  destination_service="service-b",
  le="0.01"
} 100

4. 网络错误指标

# HELP network_errors_total Network errors
# TYPE network_errors_total counter
network_errors_total{
  source_service="service-a",
  destination_service="service-b",
  error_type="connection_refused"
} 5

network_errors_total{
  source_service="service-a",
  destination_service="service-b",
  error_type="timeout"
} 2

跨可用区流量测量

云环境中，跨可用区（AZ）流量通常会产生额外费用。OBI 可以自动识别和测量跨 AZ 流量，帮助优化成本。

启用跨 AZ 流量监控

前提条件：

• Kubernetes 环境
• Node 需要有可用区标签：topology.kubernetes.io/zone

配置：

network:
  enable: true
  
  # 启用可用区检测
  cloud:
    enable: true
    
    # 云提供商类型
    provider: aws  # 或 azure, gcp, aliyun
    
    # 可用区标签键
    zone_label: topology.kubernetes.io/zone

查看跨 AZ 流量指标

# HELP network_cross_az_traffic_bytes Cross-AZ traffic in bytes
# TYPE network_cross_az_traffic_bytes counter
network_cross_az_traffic_bytes{
  source_service="service-a",
  source_az="us-east-1a",
  destination_service="service-b",
  destination_az="us-east-1b"
} 10485760

# HELP network_cross_az_traffic_cost Estimated cross-AZ traffic cost (USD)
# TYPE network_cross_az_traffic_cost counter
network_cross_az_traffic_cost{
  source_az="us-east-1a",
  destination_az="us-east-1b"
} 1.05

优化建议

根据跨 AZ 流量数据，您可以：

1. 识别热点：找出跨 AZ 流量最多的服务对
2. 优化部署：将频繁通信的服务部署在同一 AZ
3. 添加缓存：对跨 AZ 调用添加缓存层
4. 评估成本：计算跨 AZ 流量的实际成本

网络拓扑可视化

OBI 导出的网络指标可以用于构建服务网络拓扑图：

服务 A (us-east-1a)
  │
  ├─→ 服务 B (us-east-1a)  [1.2 GB/day, 5ms]
  │
  ├─→ 服务 C (us-east-1b)  [500 MB/day, 15ms] ⚠️ 跨 AZ
  │
  └─→ 数据库 (us-east-1a)  [300 MB/day, 2ms]

网络监控配置示例

Kubernetes DaemonSet 配置

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: obi-network
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: obi-network
  template:
    metadata:
      labels:
        app: obi-network
    spec:
      hostPID: true
      hostNetwork: true
      serviceAccountName: obi
      containers:
      - name: obi
        image: grafana/beyla:latest
        securityContext:
          privileged: true
          capabilities:
            add:
              - CAP_NET_ADMIN  # 网络监控需要此权限
              - CAP_BPF
              - CAP_PERFMON
        env:
        - name: BEYLA_NETWORK_ENABLE
          value: "true"
        - name: BEYLA_NETWORK_SAMPLE_RATE
          value: "100"
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "http://uptrace-grpc.yodao.cn:80"
        - name: OTEL_EXPORTER_OTLP_HEADERS
          valueFrom:
            secretKeyRef:
              name: obi-credentials
              key: dsn

分布式追踪

OBI 自动为 HTTP 和 gRPC 请求生成分布式追踪 Span，并支持跨服务的上下文传播。

Span 信息

OBI 生成的 Span 包含以下信息：

HTTP Span 属性

gRPC Span 属性

数据库 Span 属性

对于数据库调用，OBI 会创建额外的子 Span：

上下文传播

OBI 自动支持多种 Trace Context 传播协议：

支持的传播协议

1. W3C Trace Context（推荐）

   • Header: traceparent, tracestate
   • 格式: 00-{trace-id}-{span-id}-{flags}
   • 示例: traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

2. B3 Propagation

   • Single Header: b3: {trace-id}-{span-id}-{flags}
   • Multi Header: X-B3-TraceId, X-B3-SpanId, X-B3-Sampled

3. Jaeger Propagation

   • Header: uber-trace-id
   • 格式: {trace-id}:{span-id}:{parent-span-id}:{flags}

上下文传播示例

服务 A (Go) → 服务 B (Java) → 服务 C (Python)

1. 服务 A 发起请求：

   GET /api/users HTTP/1.1
   Host: service-b:8080
   traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

2. OBI 自动提取 Service B 收到请求时的 Trace Context

3. Service B 调用 Service C 时，OBI 自动注入 Trace Context：

   GET /api/details HTTP/1.1
   Host: service-c:8080
   traceparent: 00-0af7651916cd43dd8448eb211c80319c-c9ef2b3a4d5e6f7a-01

4. 在 Uptrace 中可以看到完整的调用链：

   Trace ID: 0af7651916cd43dd8448eb211c80319c
   
   Service A: GET /api/users [150ms]
     └─> Service B: GET /api/users [120ms]
           └─> Service C: GET /api/details [80ms]

与语言 Agent 协同工作

OBI 可以与传统的语言 Agent 协同工作，实现更精细的监控：

场景 1：OBI + Go Auto-Instrumentation

┌─────────────────────────────────────┐
│  Go 应用（使用 OBI 监控）            │
│                                     │
│  HTTP Server [由 OBI 捕获]          │
│    └─> Business Logic               │
│          └─> Database [由 OBI 捕获] │
└─────────────────────────────────────┘

• OBI 负责：HTTP 请求/响应、数据库查询
• 无需任何代码修改

场景 2：OBI + Java Agent

┌─────────────────────────────────────┐
│  Java 应用                           │
│                                     │
│  HTTP Server [由 OBI 捕获]          │
│    └─> Controller [由 Agent 监控]   │
│          └─> Service [由 Agent 监控]│
│                └─> DAO [由 Agent 监控]│
│                     └─> DB [由 OBI 捕获]│
└─────────────────────────────────────┘

• OBI 负责：HTTP 事务级监控、数据库查询
• Java Agent 负责：方法级监控、业务逻辑监控

混合监控配置

步骤 1：启用 OBI（全局监控）

kubectl apply -f obi-daemonset.yaml

步骤 2：为关键服务添加 Java Agent

FROM openjdk:11-jre
COPY opentelemetry-javaagent.jar /app/
COPY myapp.jar /app/
ENTRYPOINT ["java", "-javaagent:/app/opentelemetry-javaagent.jar", "-jar", "/app/myapp.jar"]

步骤 3：配置 Java Agent 与 OBI 协同

# Java Agent 配置
export OTEL_SERVICE_NAME=my-java-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project

# 启用 Trace Context 传播
export OTEL_PROPAGATORS=tracecontext,baggage

结果：

• OBI 捕获 HTTP 入口和出口流量
• Java Agent 监控应用内部的方法调用
• 两者共享相同的 Trace Context，形成完整的调用链

安全性

OBI 需要较高的系统权限才能运行 eBPF 程序。本节介绍所需权限和如何以最小权限原则运行 OBI。

所需权限

OBI 需要以下 Linux Capabilities：

最小权限配置

Docker 最小权限

避免使用 --privileged，使用精确的 Capabilities：

docker run -d \
  --name obi \
  --pid host \
  --cap-add=CAP_DAC_READ_SEARCH \
  --cap-add=CAP_SYS_PTRACE \
  --cap-add=CAP_PERFMON \
  --cap-add=CAP_BPF \
  --cap-add=CAP_CHECKPOINT_RESTORE \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80 \
  -e OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  grafana/beyla:latest

如果需要网络监控：

docker run -d \
  --name obi \
  --pid host \
  --network host \
  --cap-add=CAP_DAC_READ_SEARCH \
  --cap-add=CAP_SYS_PTRACE \
  --cap-add=CAP_PERFMON \
  --cap-add=CAP_BPF \
  --cap-add=CAP_CHECKPOINT_RESTORE \
  --cap-add=CAP_NET_ADMIN \
  -e BEYLA_NETWORK_ENABLE=true \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80 \
  -e OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  grafana/beyla:latest

Kubernetes 最小权限

不使用 privileged: true：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: obi
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: obi
  template:
    metadata:
      labels:
        app: obi
    spec:
      hostPID: true
      serviceAccountName: obi
      containers:
      - name: obi
        image: grafana/beyla:latest
        securityContext:
          runAsUser: 0
          capabilities:
            add:
              - CAP_DAC_READ_SEARCH
              - CAP_SYS_PTRACE
              - CAP_PERFMON
              - CAP_BPF
              - CAP_CHECKPOINT_RESTORE
              # 仅在需要网络监控时添加
              # - CAP_NET_ADMIN
        env:
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "http://uptrace-grpc.yodao.cn:80"
        - name: OTEL_EXPORTER_OTLP_HEADERS
          valueFrom:
            secretKeyRef:
              name: obi-credentials
              key: dsn
        volumeMounts:
        - name: sys-kernel-debug
          mountPath: /sys/kernel/debug
          readOnly: true
      volumes:
      - name: sys-kernel-debug
        hostPath:
          path: /sys/kernel/debug

systemd 最小权限

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/beyla --config /etc/beyla/config.yaml
Restart=always

# 授予必需的 Capabilities
AmbientCapabilities=CAP_DAC_READ_SEARCH CAP_SYS_PTRACE CAP_PERFMON CAP_BPF CAP_CHECKPOINT_RESTORE

# 禁止提权
NoNewPrivileges=true

# 限制系统调用（可选，提高安全性）
SystemCallFilter=@system-service
SystemCallFilter=~@privileged @resources

# 限制文件访问
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/beyla

内核版本与权限的关系

建议：使用 Linux 5.8+ 内核，以便使用最小权限原则。

TLS/SSL 支持

OBI 可以监控加密的 HTTPS 和 gRPC over TLS 流量，无需提供证书或密钥。

工作原理

OBI 使用 eBPF uprobes 拦截 SSL/TLS 库的函数调用（如 OpenSSL 的 SSL_read、SSL_write），在加密前/解密后读取明文数据。

支持的 TLS 库：

• OpenSSL 1.1.0+, 3.0+
• BoringSSL
• GnuTLS
• Go crypto/tls（内置）
• Java JSSE

配置 TLS 监控

默认启用，无需额外配置：

# TLS 监控默认启用
# 如需禁用，可以设置：
tls:
  enable: false

TLS Span 示例

Span: HTTPS GET /api/users
  - http.scheme: https
  - http.url: /api/users
  - t控运行在同一宿主机上的 Docker 容器

**步骤 1：启动您的应用**

```bash
# 示例：启动一个简单的 HTTP 服务
docker run -d \
  --name my-app \
  -p 8080:8080 \
  my-app-image:latest

步骤 2：启动 OBI

docker run -d \
  --name obi \
  --privileged \
  --pid host \
  --network host \
  -e OTEL_SERVICE_NAME=my-app \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80 \
  -e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
  -e OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /proc:/proc:ro \
  -v /sys:/sys:ro \
  grafana/beyla:latest

重要参数说明：

• --privileged：授予容器特权模式（简单，但权限较大）
• --pid host：使用宿主机的 PID 命名空间，允许 OBI 看到所有进程
• --network host：使用宿主机网络（推荐，避免网络隔离问题）
• -e OTEL_SERVICE_NAME：设置服务名称（会自动发现并使用）
• -v /sys/kernel/debug：挂载 eBPF 调试信息

步骤 3：验证

# 发送测试请求
curl http://localhost:8080/

# 查看 OBI 日志
docker logs obi

# 在 Uptrace 平台查看数据
# 访问 https://uptrace.inner.youdao.com/

Docker Compose

创建 docker-compose.yml：

version: '3.8'

services:
  # 您的应用
  my-app:
    image: my-app-image:latest
    ports:
      - "8080:8080"
    environment:
      - APP_ENV=production
  
  # OBI 监控
  obi:
    image: grafana/beyla:latest
    privileged: true
    pid: host
    network_mode: host
    environment:
      # 服务发现配置
      - BEYLA_OPEN_PORT=8080
      - OTEL_SERVICE_NAME=my-app
      
      # OTLP 导出配置（内部平台）
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://uptrace-grpc.yodao.cn:80
      - OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
      - OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project
      
      # 采样配置
      - BEYLA_TRACE_PRINTER=disabled
      - BEYLA_METRICS_INTERVAL=30s
    volumes:
      - /sys/kernel/debug:/sys/kernel/debug:ro
      - /proc:/proc:ro
      - /sys:/sys:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

启动：

docker-compose up -d

Kubernetes 部署

使用 DaemonSet 部署（推荐）

场景：在 Kubernetes 集群中监控所有 Pod

步骤 1：创建 ConfigMap

创建 obi-config.yaml：

apiVersion: v1
kind: ConfigMap
metadata:
  name: obi-config
  namespace: monitoring
data:
  beyla-config.yml: |
    # 服务发现配置
    discovery:
      services:
        - k8s_namespace: default
          k8s_pod_name: "*"
    
    # OTLP 导出配置（内部平台）
    otel_exporter_otlp:
      endpoint: http://uptrace-grpc.yodao.cn:80
      protocol: http/protobuf
      # DSN 将通过环境变量 OTEL_EXPORTER_OTLP_HEADERS 设置
    
    # 网络监控（可选）
    network:
      enable: false
    
    # 采样配置
    traces:
      sampler:
        name: traceidratio
        arg: "0.1"  # 10% 采样率
    
    # 日志级别
    log_level: info

步骤 2：创建 DaemonSet

创建 obi-daemonset.yaml：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: obi
  namespace: monitoring
  labels:
    app: obi
spec:
  selector:
    matchLabels:
      app: obi
  template:
    metadata:
      labels:
        app: obi
    spec:
      hostPID: true
      hostNetwork: true
      serviceAccountName: obi
      containers:
      - name: obi
        image: grafana/beyla:latest
        imagePullPolicy: IfNotPresent
        securityContext:
          privileged: true
          readOnlyRootFilesystem: true
          runAsUser: 0
          capabilities:
            add:
              - SYS_ADMIN
              - SYS_RESOURCE
              - SYS_PTRACE
              - NET_ADMIN
              - NET_RAW
              - BPF
              - PERFMON
        env:
        # OTLP Exporter 配置（内部平台）
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "http://uptrace-grpc.yodao.cn:80"
        - name: OTEL_EXPORTER_OTLP_PROTOCOL
          value: "http/protobuf"
        - name: OTEL_EXPORTER_OTLP_HEADERS
          value: "uptrace-dsn=http://PROJECT_TOKEN@uptrace-grpc.yodao.cn/PROJECT_ID"
        
        # 配置文件路径
        - name: BEYLA_CONFIG_PATH
          value: "/etc/beyla/beyla-config.yml"
        
        # Kubernetes 元数据
        - name: KUBE_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: KUBE_NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        
        resources:
          limits:
            memory: 300Mi
            cpu: 200m
          requests:
            memory: 100Mi
            cpu: 50m
        
        volumeMounts:
        - name: config
          mountPath: /etc/beyla
          readOnly: true
        - name: sys-kernel-debug
          mountPath: /sys/kernel/debug
          readOnly: true
        - name: proc
          mountPath: /host/proc
          readOnly: true
        - name: sys
          mountPath: /sys
          readOnly: true
        - name: run
          mountPath: /var/run
          readOnly: true
        - name: tmp
          mountPath: /tmp
      
      volumes:
      - name: config
        configMap:
          name: obi-config
      - name: sys-kernel-debug
        hostPath:
          path: /sys/kernel/debug
      - name: proc
        hostPath:
          path: /proc
      - name: sys
        hostPath:
          path: /sys
      - name: run
        hostPath:
          path: /var/run
      - name: tmp
        emptyDir: {}
      
      tolerations:
      - effect: NoSchedule
        operator: Exists
      - effect: NoExecute
        operator: Exists

步骤 3：创建 ServiceAccount 和 RBAC

创建 obi-rbac.yaml：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: obi
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: obi
rules:
- apiGroups: [""]
  resources:
  - pods
  - services
  - endpoints
  verbs:
  - get
  - list
  - watch
- apiGroups: ["apps"]
  resources:
  - deployments
  - replicasets
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: obi
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: obi
subjects:
- kind: ServiceAccount
  name: obi
  namespace: monitoring

步骤 4：部署

# 创建命名空间
kubectl create namespace monitoring

# 应用配置
kubectl apply -f obi-rbac.yaml
kubectl apply -f obi-config.yaml
kubectl apply -f obi-daemonset.yaml

# 验证部署
kubectl get daemonset -n monitoring
kubectl get pods -n monitoring -l app=obi
kubectl logs -n monitoring -l app=obi --tail=50

使用 Helm 部署

步骤 1：添加 Helm 仓库

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

步骤 2：创建 values.yaml

创建 obi-values.yaml：

# 镜像配置
image:
  repository: grafana/beyla
  tag: latest
  pullPolicy: IfNotPresent

# 部署模式：daemonset 或 deployment
deploymentMode: daemonset

# 资源限制
resources:
  limits:
    memory: 300Mi
    cpu: 200m
  requests:
    memory: 100Mi
    cpu: 50m

# OTLP 导出配置（内部平台）
env:
  OTEL_EXPORTER_OTLP_ENDPOINT: "http://uptrace-grpc.yodao.cn:80"
  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf"
  OTEL_EXPORTER_OTLP_HEADERS: "uptrace-dsn=http://PROJECT_TOKEN@uptrace-grpc.yodao.cn/PROJECT_ID"

# Beyla 配置
config:
  discovery:
    services:
      - k8s_namespace: default
        k8s_pod_name: "*"
  
  traces:
    sampler:
      name: traceidratio
      arg: "0.1"
  
  log_level: info

# 网络监控（可选）
networkMonitoring:
  enabled: false

# 容忍度（允许在所有节点运行）
tolerations:
  - effect: NoSchedule
    operator: Exists
  - effect: NoExecute
    operator: Exists

步骤 3：安装

helm install obi grafana/beyla \
  --namespace monitoring \
  --create-namespace \
  -f obi-values.yaml

步骤 4：验证

helm status obi -n monitoring
kubectl get pods -n monitoring -l app.kubernetes.io/name=beyla

Pod 注解控制

通过 Pod 注解可以控制是否监控特定 Pod：

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    # 启用 OBI 监控
    beyla.grafana.com/enabled: "true"
    
    # 自定义服务名称
    beyla.grafana.com/service-name: "my-custom-service"
    
    # 指定监控端口
    beyla.grafana.com/port: "8080"
spec:
  containers:
  - name: app
    image: my-app:latest
    ports:
    - containerPort: 8080