故障排查

从最早失败的阶段开始。先记录构建身份和故障时间，保留 WAL；不要用反复重启代替定位。

没有找到目标

确认 match.executable 与 /proc/PID/exe 的绝对路径完全相同，UID、cgroup、Pod label 和 namespace 均匹配。检查同优先级策略冲突、排除策略、max_targets 以及多个管理器范围重叠。短进程可能在轮询/加载前退出。

sudo netflowscout status --component endpoint \
  --config /etc/netflowscout/netflowscout.json \
  --endpoint-config /etc/netflowscout/endpoints/billing.json

找到目标但挂载失败

运行 doctor，检查 BTF、root/有效 capabilities、目标 PID 和文件系统可见性、libssl 映射、Go 版本、探针/BPF 配套。HTTP/3 还需要目标 DWARF、符号及支持的 quic-go。混合运行时显式配置 module；无法支持的版本不可通过扩大协议签名修复。

attached 但没有业务

确认挂载后确实有新请求，主配置 application_source 正确，协议/方向/端口识别无歧义，端点和分析器使用相同 stream socket 与插件目录。检查捕获/桥接/分析输入丢弃、incomplete、解析异常。普通 TLS 探针不捕获 QUIC。

若 canary 通过、真实业务失败，优先检查探针与识别前半段。canary 的 capture=not_verified 是预期语义。

有业务但没有事件

检查 on 是否匹配：http.request 需要开启 request_events；http.transaction 需要事务结束。用 rules test 查看 where、when、缺失字段、冷却、窗口、迟到与预算计数。新窗口规则先暖机，固定窗口关闭后才判断。检查实际规则版本，不只检查磁盘文件。

插件无法加载或重载

运行完整 check 和 plugin verify，核对 ABI、host_schema_version、schema、协议/端口冲突、模块摘要和声明内存。插件及父目录须允许非 root 分析器读取/遍历。schema 或敏感性变更需要协调重启；兼容重载后老连接显示旧代际是正常行为。

事件积压或 Dataway 失败

查看每个输出端的待确认数和失败状态，确认基础 URL、服务环境中的 token_env、DNS/TLS 与接收端状态。doctor 检查当前命令环境，不读取 systemd 环境值。401/403 有长退避；修正后重启主服务可立即重试。不要在工单中粘贴 token、完整请求 URL 或原始响应。

磁盘满先恢复可用空间；保留已提交 WAL。文件轮转保留量与 WAL 队列容量不同。HTTP ACK 后无法检索时，在目标日志平台按 event_id 查询并检查索引路径。

TUI 显示 UNKNOWN / STALE

检查心跳是否新鲜、metrics 是否 loopback 启用、所选文件是否包含所有活动端点、状态 PID 是否对应当前服务。权限不足和无流量应分别处理，不能将最后快照当作当前健康。

提交可用证据

使用诊断归档，附 version/support、所选范围、时间及去敏复现。说明是配置检查、模拟回放、真实 TLS 还是物理网卡问题，便于界定结论。