> ## Documentation Index
> Fetch the complete documentation index at: https://hilt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 常见的 DMG 采集器故障及其解决方法。

## 安装时 BTF / BPF 加载失败

**内核 5.8+：** 如果 `/sys/kernel/btf/vmlinux` 缺失，说明内核在构建时未启用 `CONFIG_DEBUG_INFO_BTF=y`。请升级到带原生 BTF 的内核，或使用已内置 BTF 的发行版（参见[系统要求](https://hilt.ai/docs/zh/linux-collector/system-requirements.md)）。

**内核 4.18–5.7：** 不需要原生 BTF。请确保已完整解压发布 tarball，使 `btf/` 目录与二进制文件位于同一目录。如果安装仍然失败，请验证捆绑的 BTF 是否与当前运行的内核匹配。

## DaemonSet 因 BPF 加载失败陷入 CrashLoopBackOff

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

可通过以下命令验证：

```bash theme={null}
kubectl describe pod -l app=dag-agent
```

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

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

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

1. 使用 `getent hosts` 验证节点上的 DNS 解析。如果该域名无法解析，可能是缺少私有 Route 53 关联。
2. 确认连通性。如果请求挂起，请检查 PrivateLink 安全组是否允许来自该节点所在安全组的流量。
3. 确保所配置的 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` 仍然存在，这是有意为之。卸载过程会保留日志，以便进行移除后分析或交接。如果需要干净的主机状态，请手动删除该目录。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.