beyla

Grafana Beyla

文档：https://grafana.com/docs/beyla/latest/

通过 eBPF 实现零代码 HTTP / gRPC / DB 插桩。生成 OTLP 追踪数据和 Prometheus 指标。

前置条件

• 启用 BTF 的 Linux 内核 5.8+（必须存在 ls /sys/kernel/btf/vmlinux）
• Root 或 CAP_SYS_ADMIN（或在 Kubernetes 中设置 privileged: true + hostPID: true）
• x86_64 或 ARM64
• 可从 Beyla 访问的 OTLP 接收器（Tempo、Alloy、OTel Collector）

常见工作流

1. 使用 Docker 插桩单个二进制文件

# 1. Run Beyla against the app's port (the app must already be running, listening on 8080)
docker run --privileged --pid=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -e BEYLA_OPEN_PORT=8080 \
  -e BEYLA_PROMETHEUS_PORT=8999 \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
  -p 8999:8999 \
  grafana/beyla

# 2. Generate some traffic
curl http://localhost:8080/ ; curl http://localhost:8080/api/users/42

# 3. Verify Beyla emitted metrics — should list http_server_request_duration_seconds + counters
curl -s http://localhost:8999/metrics | grep -E '^http_(server|client)_request_duration'

# 4. Verify traces — in Grafana Explore on Tempo, search by service.name (default = process name)
#    Or: query Tempo's search API for spans with service.name="<app>"

2. 部署为集群范围的 DaemonSet

完整的 DaemonSet + RBAC YAML 位于 references/kubernetes.md。应用后：

# 1. Verify DaemonSet rollout
kubectl -n monitoring rollout status ds/beyla

# 2. Verify pods are Running, one per node
kubectl -n monitoring get pods -l app=beyla -o wide

# 3. Verify eBPF probes attached (no errors mentioning BTF or "permission denied")
kubectl -n monitoring logs ds/beyla --tail=50 | grep -Ei 'error|fail|btf' || echo "clean"

# 4. Verify telemetry is flowing — check the Tempo/Alloy receiver for spans from the cluster
#    Or scrape one pod directly:
kubectl -n monitoring port-forward ds/beyla 8999:8999 &
curl -s localhost:8999/metrics | head

3. 通过 Alloy 发送到 Grafana Cloud

# beyla-config.yml
otel_traces_export:  { endpoint: http://alloy:4318 }
otel_metrics_export: { endpoint: http://alloy:4318 }

# Verify Alloy is forwarding — check Alloy UI (localhost:12345) for the
# otelcol.receiver.otlp.beyla component showing received spans/metrics > 0.

完整的 Alloy + Beyla YAML：references/config.md。

故障排除

• failed to load BPF object → 内核版本低于 5.8 或缺少 BTF；检查 /sys/kernel/btf/vmlinux
• Tempo 中没有跨度数据，但 Prometheus 指标正常 → 检查 OTEL_EXPORTER_OTLP_ENDPOINT、协议（http 还是 grpc）和端口（4318 http / 4317 grpc）
• HTTP 路由基数激增 → 设置 routes.unmatched: heuristic 并添加模式（参见 references/config.md）
• Pod 因 CrashLoopBackOff 不断重启 → 可能缺少 hostPID: true 或 privileged: true / 所需的功能

资源

• Beyla 文档
• Beyla GitHub
• references/config.md — 完整配置、环境变量、采样器、路由装饰器、生成的指标表、运行时矩阵
• references/kubernetes.md — DaemonSet + RBAC + 发现筛选器 + Helm