故障排查 - Hilt Documentation

安装时 BTF / BPF 加载失败

内核 5.8+： 如果 /sys/kernel/btf/vmlinux 缺失，说明内核在构建时未启用 CONFIG_DEBUG_INFO_BTF=y。请升级到带原生 BTF 的内核，或使用已内置 BTF 的发行版（参见系统要求）。 内核 4.18–5.7： 不需要原生 BTF。请确保已完整解压发布 tarball，使 btf/ 目录与二进制文件位于同一目录。如果安装仍然失败，请验证捆绑的 BTF 是否与当前运行的内核匹配。

DaemonSet 因 BPF 加载失败陷入 CrashLoopBackOff

如果 DaemonSet 因 BPF 程序加载失败进入 CrashLoopBackOff，问题通常与缺少内核挂载或特权不足有关。请确保容器内已挂载 /sys/kernel/btf 和 /sys/kernel/debug，并且 Pod 以 privileged: true 运行。可通过以下命令验证：

kubectl describe pod -l app=dag-agent

并检查容器内的文件系统访问情况。

代理处于“发送模式（Ship mode）”但仪表盘中没有事件

如果代理日志显示处于“发送模式（Ship mode）”，但仪表盘中并未出现事件：

使用 getent hosts 验证节点上的 DNS 解析。如果该域名无法解析，可能是缺少私有 Route 53 关联。
确认连通性。如果请求挂起，请检查 PrivateLink 安全组是否允许来自该节点所在安全组的流量。
确保所配置的 URL 正确：它必须包含 /ingest 路径（例如 https://<name>-ingest.hilt.ai/ingest）。采集器会将遥测原样 POST 到 DAG_SHIP_URL —— 仅有域名而没有路径会把事件发送到错误位置，通常返回 404/405。

环形缓冲区丢弃计数偏高

如果在繁忙主机上观察到环形缓冲区丢弃计数偏高，请增大所配置的 ringbuf_size（例如增大到 8M 或 16M）并重启代理。可通过详细模式（-v）或代理日志监控丢弃情况，丢弃通常表明持续的事件吞吐量已超出当前缓冲区容量。

卸载后日志仍然保留

如果卸载后 /var/log/dag-agent/events.jsonl 仍然存在，这是有意为之。卸载过程会保留日志，以便进行移除后分析或交接。如果需要干净的主机状态，请手动删除该目录。