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