主题
eBPF 全链路观测 操作文档(Beyla + Tempo)
日常运维手册。前提:
alias k='/tmp/bin/kubectl'; export KUBECONFIG=~/.kube/config-122.31
一、看板与入口
1.1 RED 总览看板
Grafana(rancher-monitoring)→ Dashboards → eBPF APM - RED 总览(uid ebpf-apm-red):
- 请求速率 / 错误率 / P95 延迟:按
命名空间/服务分线,数据源 Prometheus(Beyla 指标) - 服务拓扑 Node Graph:数据源 Tempo(底层查 Prometheus 的
traces_service_graph_*) - 最近 Traces:TraceQL 查询面板
1.2 指标 → Trace 跳转(exemplar)
Prometheus 数据源已配 exemplar 联动:Beyla 的 histogram 指标带 trace_id exemplar。在 Explore 里查 http_server_request_duration_seconds_bucket,曲线上的 exemplar 点 → 查看 Trace 直接跳到 Tempo 对应 trace。
1.3 Explore Traces(免写查询)
Grafana 已装 grafana-exploretraces-app 插件:Explore → Traces(或左侧菜单 Explore Traces),选 Tempo 数据源,按 RED 三率图形化下钻,无需手写 TraceQL。
1.4 手写 TraceQL 速查
| 需求 | TraceQL |
|---|---|
| 某服务全部 trace | { resource.service.name = "knative-serving" } |
| 慢请求(>1s) | { duration > 1s } |
| 5xx 错误 | { status = error } |
| 按路由 | { name = "GET /" && resource.k8s.namespace.name = "default" } |
命令行查询:
bash
k -n observability port-forward svc/tempo 13200:3200 &
curl -s 'localhost:13200/api/search?limit=20' # 最近 trace
curl -s 'localhost:13200/api/search?q=%7Bstatus%3Derror%7D' # TraceQL(URL 编码)
curl -s 'localhost:13200/api/v2/traces/<traceID>' # 按 ID 取完整 span 树二、指标速查(Prometheus)
bash
k -n cattle-monitoring-system port-forward svc/rancher-monitoring-prometheus 19090:9090 &| 需求 | PromQL |
|---|---|
| 服务 QPS | sum by (k8s_namespace_name, service_name) (rate(http_server_request_duration_seconds_count[5m])) |
| 5xx 错误率 | sum by (service_name) (rate(http_server_request_duration_seconds_count{http_response_status_code=~"5.."}[5m])) / sum by (service_name) (rate(http_server_request_duration_seconds_count[5m])) |
| P99 延迟 | histogram_quantile(0.99, sum by (service_name, le) (rate(http_server_request_duration_seconds_bucket[5m]))) |
| spanmetrics(按 span) | sum by (service_name, span_name) (rate(traces_spanmetrics_calls_total[5m])) |
| 服务拓扑边 | traces_service_graph_request_total |
| 数据库调用(Redis/SQL) | redis_server_duration_seconds_* / sql_client_duration_seconds_* |
三、告警
PrometheusRule ebpf-apm-red(ns observability,复用现有 Alertmanager 飞书路由):
| 告警 | 条件 | 处理 |
|---|---|---|
| AppHighErrorRate | 应用 5xx 比例 >2%(5m) | 看板定位服务 → exemplar 跳 trace → 查应用日志 |
| AppHighLatencyP99 | P99 >1s(5m) | 同上;配合 spanmetrics 看慢在哪个 span |
| BeylaDown | beyla target 消失 | 查 DS:k -n observability get pods -l app=beyla -o wide |
| TempoDown | tempo target down | k -n observability logs deploy/tempo --tail=100,常见:PVC 满 |
四、日常运维操作
4.1 修改 Beyla 采集范围 / 配置
bash
k -n observability edit cm beyla-config # 或改本地 beyla.yaml 后 apply
k -n observability rollout restart ds beyla # ⚠️ 必须手动重启,CM 变更不触发
k -n observability rollout status ds beyla4.2 临时打开 debug 日志
beyla-config 的 log_level: debug + rollout restart。关键日志模式:
| 日志 | 含义 |
|---|---|
processes matching selection criteria len=N | N=0 是事故信号(选择器没匹配到任何进程) |
instrumenting process cmd=... type=go | 进程被成功埋点 |
component=otelcfg.TracesConfig ... endpoint=... | trace 导出器初始化成功 |
metadata does not match attr=k8s_namespace value=... | 选择器 glob/正则写错(踩坑①) |
4.3 健康巡检
bash
# Beyla 各节点 trace 导出计数(应持续增长)
for P in $(k -n observability get pods -l app=beyla -o jsonpath='{.items[*].metadata.name}'); do
k -n observability port-forward pod/$P 19099:9099 >/dev/null 2>&1 &
sleep 1; echo "$P: $(curl -s localhost:19099/metrics | grep '^beyla_otel_trace_exports_total')"; kill %1 2>/dev/null
done
# Tempo 磁盘占用(NFS PVC)
k -n observability exec deploy/tempo -- df -h /var/tempo 2>/dev/null || echo "(distroless 无 df,改用 PVC 指标 kubelet_volume_stats_used_bytes)"4.4 Tempo 空间清理
local backend 按 block_retention: 48h 自动清理。若 PVC 告警:临时缩短保留期(tempo.yaml 的 block_retention → 24h,重启 deploy),或扩 PVC。
4.5 升级
images.txt改版本号 →./deploy.sh --sync- 改
beyla.yaml/tempo.yaml镜像 tag → apply + rollout status - 升级前先看 changelog:Beyla v3 → OBI 更名后配置结构可能变;Tempo 3.x 架构大改,勿直接跳
五、排障速查
| 症状 | 排查路径 |
|---|---|
| Tempo 搜不到 trace | ① Beyla debug 日志 matching selection criteria len 是否 >0;② :9099 的 beyla_ebpf_tracer_flushes_count / beyla_otel_trace_exports_total 是否增长;③ beyla-config 键名是否 otel_traces_export(踩坑②);④ 用 curl pod 直发 OTLP JSON 到 :4318/v1/traces 隔离 Tempo 接收器(踩坑⑥) |
| 有 RED 指标但无 trace | 正常——v3 两条管线独立(踩坑④),按上一条查 trace 侧 |
| 某个服务无数据 | 是否在 exclude_instrument;是否 Java TLS(已知限制);进程存活 <5s 会被 min_process_age 跳过 |
| trace 只有单服务 span,跨服务断链 | 已知限制:未加 CAP_SYS_ADMIN,Go context propagation 未启用 |
| Prometheus 无 spanmetrics | 查 Prometheus 日志 remote_write 错误;确认 --web.enable-remote-write-receiver 仍在(chart 升级可能还原);查 tempo 日志 metrics_generator |
| Node Graph 空白 | servicegraph 需要 client/server 双侧 span;单 span 服务不成边;查 traces_service_graph_request_total 是否有值 |
| Grafana Tempo 数据源消失/变只读配置丢失 | rancher-monitoring chart 升级还原了数据源 CM,重跑 deploy.sh 第 6 步 |
| Beyla pod OOM / CPU 高 | 默认无 limit;埋点进程过多的节点加 resources.limits,或用 exclude 缩小范围 |