【Tetragon / eBPF】节流与观测税：cgroup-rate、Post.rateLimit 与环缓冲压力
内容提要
本文讨论Tetragon v1.7.0中事件可能丢失的三层原因：cgroup-rate按CPU节流仅限EXEC/EXIT事件，超限时暂停投递并发出THROTTLE信号；Post.rateLimit按线程和参数前40字节抑制重复事件；环缓冲压力导致事件丢失。需区分这些机制，避免误判为策略未匹配。
延伸解读
三层丢失的区分要点
事件缺失可能源于cgroup-rate、Post.rateLimit或环缓冲压力，三者机制不同。cgroup-rate仅限EXEC/EXIT且按CPU节流，超限时发出THROTTLE_START；Post.rateLimit按线程和参数前40字节抑制重复事件，无显式信号；环缓冲压力则通过lost_total等指标体现。误判为策略未匹配前，应先检查这些信号。
cgroup-rate的局限
cgroup-rate默认关闭，仅覆盖PROCESS_EXEC和PROCESS_EXIT，且阈值按per-CPU计算。多核环境下，每核低于阈值但总和超限时不会节流，这是文档明确的限制。节流期间事件不投递，但THROTTLE_STOP需稳定5秒后才发出，排障时需注意时间窗口。
Post.rateLimit的40字节键
Post.rateLimit依赖内核v5.3+，默认按线程限流，每个被检查参数仅用前40字节作为键。这意味着长路径或长sockaddr可能因前40字节相同而被误判为重复，导致漏限流；反之，40字节后分叉的参数会视为不同键，限流不生效。配置时需评估参数长度对限流效果的影响。
环缓冲丢失的指标解读
环缓冲压力导致的丢失可通过多个指标区分：tetragon_bpf_missed_events_total表示内核写入失败，tetragon_observer_ringbuf_events_lost_total表示ring buffer丢失，tetragon_observer_ringbuf_queue_events_lost_total表示用户态队列丢失，tetragon_notify_overflowed_events_total表示listener溢出。这些指标应分别查看，避免混淆。
Q&A
Tetragon v1.7.0 中 cgroup-rate 节流机制的作用范围是什么？
cgroup-rate 只对 base sensor 的 PROCESS_EXEC 和 PROCESS_EXIT 事件进行节流，且按 per-CPU 监视。当某个 CPU 上事件速率超过阈值时，该 CPU 上该 cgroup 的事件会被暂停投递，直到速率低于限值并稳定 5 秒后恢复。
如何配置 Tetragon 的 cgroup-rate 参数？
通过 --cgroup-rate 参数配置，语法为 <events,interval>，例如 1000,1s 表示每秒 1000 个事件。默认关闭，当 opts.Events 或 opts.Interval 为 0 时禁用。配置成功时日志会显示 Cgroup rate started。
THROTTLE_START 和 THROTTLE_STOP 事件分别代表什么？
THROTTLE_START 表示某个 cgroup 在某个 CPU 上超过了速率阈值，开始节流；THROTTLE_STOP 表示速率重新低于上限并稳定 5 秒后，节流结束。THROTTLE_START 由 BPF 发送，THROTTLE_STOP 由用户态 ticker 产生。
Post.rateLimit 是如何工作的？它和 cgroup-rate 有什么区别？
Post.rateLimit 是选择器级别的限流，针对同一线程、同一动作、在时间窗口内且被检查参数前 40 字节相同的重复事件进行抑制。它适用于所有 TracingPolicy 钩子事件，而 cgroup-rate 只针对 EXEC/EXIT 事件。rateLimit 默认按线程，可通过 rateLimitScope 扩展。
Tetragon 中哪些指标可以用于诊断事件丢失？
相关指标包括：tetragon_observer_ringbuf_events_lost_total（ring buffer 丢失）、tetragon_observer_ringbuf_queue_events_lost_total（用户态队列丢失）、tetragon_bpf_missed_events_total（内核 perf_event_output 失败）、tetragon_notify_overflowed_events_total（listener 缓冲满）。这些指标帮助定位管道容量问题。
当策略匹配但看不到 process_exec 事件时，可能的原因有哪些？
可能原因包括：1) cgroup-rate 节流导致 EXEC/EXIT 事件被暂停；2) Post.rateLimit 抑制了重复事件；3) ring buffer 或用户态队列溢出导致事件丢失。需要区分这些机制，避免误判为策略未匹配。
cgroup-rate 的 per-CPU 特性会带来什么限制？
由于阈值按 per-CPU 监视，当事件分散在多颗 CPU 上时，只有超过阈值的 CPU 会被节流。因此，如果每颗 CPU 的速率都低于阈值，但总和远高于阈值，则不会触发节流。这是文档明确指出的限制。
Post.rateLimit 对内核版本有什么要求？
Post.rateLimit 需要内核 v5.3 及以上版本，因为参数前 40 字节的比较依赖该版本的内核特性。如果内核低于 5.3，rateLimit 不会生效。
