【Tetragon / eBPF】运维与导出工程：metrics 更名、JSON 轮转与 SIEM 接线边界
内容提要
Tetragon v1.7.0升级后，merge指标合并为带status标签的单一计数器，gRPC默认地址改为Unix socket。运维需更新告警表达式和客户端连接，注意JSON文件导出与gRPC流所见集合不同，SIEM仅能获取文件sink内容。排查事件缺失时，应区分merge配对、ringbuf丢失和导出计数三层问题。
延伸解读
指标更名后的排障陷阱
v1.7.0 将 merge 相关的两个计数器合并为一个带 status 标签的计数器，旧告警表达式会静默失效。排查时需注意：merge_total 只反映 kprobe/kretprobe 配对情况，不代表策略匹配或 JSON 导出成功。status="error" 升高可能意味着用户态看到残缺的 enter/exit 事件，而非完整调用。同时，MergePushed 计数仅表示进入合并队列，不保证最终成功，需与 ringbuf 丢失区分。
SIEM 与 gRPC 的可见集合差异
SIEM 通过文件 sink 只能看到经过 allow/deny、字段过滤、脱敏和导出限流后的事件子集，而 gRPC 流（如 tetra getevents）不受这些 JSON 过滤约束。因此，SIEM 事件少于 tetra 是正常现象，并非采集器故障。排查时应先确认文件路径、过滤规则和轮转后的 inode 问题，而非直接修改 TracingPolicy。
gRPC 默认地址变更的破坏面
v1.7.0 将默认 gRPC 地址从 localhost:54321 改为 Unix socket（/var/run/tetragon/tetragon.sock），旧客户端若不更新将连接失败。需注意：Unix socket 仅限特权用户访问，非 root 容器可能无法打开；相对路径写法（如 unix://var/run/...）会导致 URI 解析错误；从宿主机挂载 socket 时需确保路径一致。若需 TCP，必须显式配置。
导出计数器的正确解读
tetragon_events_exported_total 仅反映文件 sink 写出的数量，不代表 SIEM 已摄入。events_last_exported_timestamp 可作为文件 sink 存活探针，但无法证明采集器跟随了轮转后的新文件。tetragon_events_total 高于 exported_total 时，差额可能来自 JSON 过滤、导出限流或未开启文件导出。三者不能互相替代，需分层排查。
Q&A
Tetragon v1.7.0 中 merge 指标发生了哪些变化？
v1.7.0 删除了 tetragon_generic_kprobe_merge_errors_total 和 tetragon_generic_kprobe_merge_ok_total，替换为单一的 tetragon_generic_kprobe_merge_total，并通过 status 标签区分 ok 或 error。
升级到 Tetragon v1.7.0 后，如何调整告警表达式以监控 merge 错误？
应将告警表达式从旧的 _errors_total 和 _ok_total 改为 tetragon_generic_kprobe_merge_total{status="error"} 和 tetragon_generic_kprobe_merge_total{status="ok"}。
Tetragon v1.7.0 中 gRPC 默认地址是什么？
默认地址从 localhost:54321 改为 Unix socket：unix:///var/run/tetragon/tetragon.sock。
为什么 SIEM 采集到的 Tetragon 事件比 tetra getevents 少？
因为 SIEM 通常采集 JSON 文件（tetragon.log），而 JSON 文件经过 allow/deny 过滤、字段过滤、脱敏和导出限流，而 gRPC 流（如 tetra getevents）不受这些过滤影响，所以两者看到的集合不同。
Tetragon v1.7.0 中 JSON 文件默认路径是什么？
默认路径是 /var/run/cilium/tetragon/tetragon.log，可通过 export-filename 配置覆盖。
如何判断 Tetragon 文件导出是否正常工作？
可以监控 tetragon_events_exported_total 和 tetragon_events_last_exported_timestamp 指标，如果时间戳持续更新且计数增加，说明文件导出正常。
Tetragon v1.7.0 中，如果第三方 gRPC 客户端连接失败，可能的原因是什么？
可能原因包括：客户端仍使用旧的 localhost:54321 地址；Unix socket 路径写错（如少一杠）；非 root 容器无权限访问 socket；socket 未正确挂载到容器。
Tetragon v1.7.0 中，JSON 文件导出与 gRPC 流在事件过滤上有什么区别？
JSON 文件导出受 allow/deny 列表、字段过滤和脱敏影响，而 gRPC 流不受这些限制，因此两者看到的事件集合可能不同。
