DeepFlow Agent 故障排查指南：注册失败、协议解析、资源识别与配置方式

1.1 检查 Domain 与 Agent Group Config 配置主机进程部署需要完成两个步骤创建 Host Domain类型为agent_sync创建 Agent Group Config采集器组配置这两个步骤缺一不可。agent_sync 类型 Domain 只能创建一个多了会导致注册异常。排查步骤检查 Host Domain 是否已创建# 确认列表中存在类型为 agent_sync 的 Domain deepflow-ctl domain list检查 Agent Group Config 是否已创建deepflow-ctl agent-group-config list解决方案如果缺少 Host Domainunset DOMAIN_NAME DOMAIN_NAMElegacy-host # 自定义 domain 名称 cat EOF | deepflow-ctl domain create -f - name: $DOMAIN_NAME type: agent_sync EOFDomain 用于让 deepflow-agent 以自同步方式将服务器网络信息发送至 deepflow-server类似于监控 K8s 集群时创建 K8s Domain。如果缺少 Agent Group Config通过 deepflow-ctl 创建inputs: resources: workload_resource_sync_enabled: true采集器组配置用于在无法通过云平台 API 同步资源的场景下同步物理服务器或虚拟机的资源信息。注意事项Domain 只需创建一个创建多个会导致 Agent 注册异常两步操作缺一不可2.1.2 检查 Server 网段配置DeepFlow Server 通过local_ip_ranges配置识别局域网网段。如果 Agent 的 IP 不在该配置范围内会导致Agent 无法正常注册某些 IP 在 metrics 中被聚合为0.0.0.0广域网 IP排查步骤获取 Agent 的 IP 地址检查 Server 配置中的local_ip_ranges# kubectl edit cm -n deepflow deepflow # 默认配置 local_ip_ranges: - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 - 169.254.0.0/15 - 224.0.0.0-240.255.255.255确认 Agent IP 是否在配置的网段范围内。解决方案更新 Server 配置将 Agent 所在网段添加到local_ip_ranges更新 Server 配置文档关于 0.0.0.0 广域网 IP在 DeepFlow 中0.0.0.0代表广域网 IP。当 IP 不在local_ip_ranges中时数据类型IP 展示说明Metrics0.0.0.0聚合为广域网 IPRequest Log真实 IP保留原始 IP判断方法在 Request Log 面板中通过is_internettag 判断值为 true 时是广域网。如果需要在 Metrics 中也展示真实 IP将对应网段添加到 Server 的local_ip_ranges配置中。网卡内/外网类型判断规则网卡配置子网类型判断单个网卡仅有单个 IP且未包含在local_ip_ranges中自动识别为外网单个网卡有多个 IP任意 1 个 IP含 IPv4、IPv6未包含在local_ip_ranges中自动识别为外网如果发现网卡的子网类型识别错误检查该网卡的所有 IP 是否都在local_ip_ranges配置范围内。2.1.3 检查主机名是否重名多台主机使用相同的主机名会导致注册失败。排查步骤确认环境中是否存在重名主机。解决方案方式一推荐修改 DeepFlow Agent 配置编辑 Agent 注册配置默认路径/etc/deepflow-agent/deepflow-agent.yaml# Agent 注册时使用自定义名称上报 # https://github.com/deepflowio/deepflow/blob/main/agent/config/deepflow-agent.yaml#L35 override-os-hostname: unique-hostname-001重启 Agent 后生效。方式二修改系统主机名hostnamectl set-hostname unique-hostname-001不推荐直接修改主机名可能影响其他依赖主机名的应用。通过配置覆盖更灵活。2.1.4 检查是否通过 LB 连接 Server如果 Agent 通过负载均衡器LB连接 Server可能导致注册失败。详见3.1 通过 LB 连接 Server 导致的注册失败2.2 K8s Pod 部署K8s 部署通过 Helm Chart 安装 deepflow-agent 到集群中默认以 DaemonSet 形式运行在每个节点上。Agent 注册失败排查2.2.1 检查 Pod 运行时间与初始化状态DeepFlow 部署包含多个组件Server、Agent、Database 等首次部署需要较长的初始化时间数据库初始化Server 初始化Agent 连接 Server 完成注册排查步骤确认所有 Pod 状态正常kubectl get pods -n deepflow所有 Pod 应处于Running状态。等待 5-6 分钟后检查 Agent 注册状态deepflow-ctl agent list在 K8s 部署中Agent Pod 的 ConfigMap 中 Server 地址配置为 Server Service Name。由于 Server 和 Agent 在同一集群内网络连通性一般不会有问题。注册未完成通常是因为初始化未完成等待即可。如果等待 5 分钟后仍未注册成功尝试重启 Agent Podkubectl delete pods -n deepflow -l appdeepflow-agent注意事项确保 Agent 能够匹配到网卡的 interface_regex 配置否则无法采集数据网卡匹配正则配置参考2.2.2 检查是否通过 LB 连接 Server如果 Agent 通过负载均衡器LB连接 Server可能导致注册失败。详见3.1 通过 LB 连接 Server 导致的注册失败数据同步问题排查2.2.3 检查 K8s 集群资源同步DeepFlow 对 K8s 资源的展示有特定规则某些场景下资源会被过滤掉。1. 当前资源没有请求/响应流量DeepFlow 认为没有流量的资源没有展示意义。如果某个 Pod 从未接收或发送过请求该资源可能不会在数据中展示。排查方法检查该资源是否有业务流量尝试发送测试请求到该资源2. 没有上层/下层资源关联DeepFlow 依赖资源的上下层关系进行展示孤立资源可能被过滤资源类型不展示的情况Namespace该 Namespace 下没有任何 PodServiceService 没有关联任何 PodPodPod 没有上层资源如 Deployment、DaemonSet、StatefulSet仅为单独的 PodDeepFlow 认为没有完整上下层关系的资源没有展示意义。排查方法检查资源是否有关联的上下层资源确认 Pod 是否通过控制器Deployment/DS/STS创建3. 资源不是 K8s 原生资源如果资源是通过自定义 Operator 创建的非 K8s 原生 KindDeepFlow 可能无法正确识别其上层资源关系。示例kube-prometheus 项目中的 Prometheus Pod其上层 Kind 为Prometheus自定义 CRD而非 K8s 原生的 Deployment/StatefulSet。排查方法检查资源的ownerReferences字段确认是否为 K8s 原生资源如果是自定义 CRD目前 DeepFlow 无法识别K8s 资源不展示的常见原因原因说明解决方案没有流量资源从未有请求/响应发送测试流量没有上下层关系孤立资源单独的 Pod、未关联 Pod 的 Service 等确保资源有完整的层级关系非原生资源通过自定义 Operator 创建目前可能无法完美支持3. 通用排查案例3.1 通过 LB 连接 Server 导致的注册失败默认 server 会下发自己的节点 IP 给 agent 作为控制/数据面通信 IP。当 Agent 无法直接连接 Server必须通过 LB 时需要配置以下四个参数参数说明文档链接proxy_controller_ip用于设置 agent 与 server 通信的控制面通信 IP配置文档proxy_controller_port对应的端口号配置文档ingester_ip用于设置 agent 与 server 通信的数据面通信 IP配置文档ingester_port对应的端口号配置文档配置示例在 agent-group-config 中添加global: communication: proxy_controller_ip: 10.0.0.100 # LB IP proxy_controller_port: 30035 ingester_ip: 10.0.0.100 ingester_port: 300333.2 缺少协议数据DeepFlow 支持多种应用层协议解析但 v6.5 版本后为了降低资源开销Agent 默认仅解析以下协议HTTPHTTP2/gRPCMySQLRedisKafkaDNSTLS其他协议需要手动启用例如PostgreSQL、MongoDB、RabbitMQ 等。开源版不支持 Oracle 协议。完整协议支持列表解决方案如果需要解析其他协议通过 deepflow-ctl 添加在配置中添加需要启用的协议processors: request_log: application_protocol_inference: enabled_protocols: - HTTP - HTTP2 - MySQL - Redis - Kafka - DNS - TLS - PostgreSQL # 手动添加3.3 eBPF 加载失败典型错误日志[eBPF] WARN func load_obj__progs() [user/load.c:546] bcc_prog_load() failed. name: df_T_exit_write, Invalid argument errno: 22 [eBPF] WARN func ebpf_obj_load() [user/load.c:854] eBPF load programs failed. (errno 22) [eBPF] INFO release object (socket-trace-bpf-linux-common) ... [eBPF] INFO release object done [eBPF] WARN func tracer_bpf_load() [user/tracer.c:525] bpf load socket-trace-bpf-linux-common failed, error:Invalid argument (22). [src/trident.rs:2339] ebpf collector error: EbpfRunningErroreBPF 加载失败是因为 DeepFlow 对当前使用的系统或内核版本不适配。解决方案情况一使用通用操作系统如果你使用的是通用操作系统Ubuntu、CentOS、Debian、Fedora 等按以下步骤收集信息并反馈给社区查看内核版本uname -a hostnamectl运行内核结构偏移量检查工具使用 show-kernel-struct-offset 项目# 下载并编译工具 git clone https://github.com/deepflowio/show-kernel-struct-offset.git cd show-kernel-struct-offset make将结果发送到 DeepFlow 社区在 GitHub Issues 中提交或发送到 DeepFlow 开源社区群社区会根据提供的信息适配对应的内核版本。情况二使用自定义系统或内核如果你使用的是自定义操作系统或内核需要自行适配参考 PR 示例自定义内核适配示例前提条件检查在排查 eBPF 问题时先确认环境满足要求运行权限及内核要求3.4 配置识别异常可能的原因配置下发延迟或失败Agent 未正确识别 Server 下发的配置配置格式错误导致解析失败Agent 版本不支持该配置项排查步骤1. 查看组件版本# 查看 Agent commit 版本 deepflow-agent -v # 查看 Server commit 版本 deepflow-server -v2. 查看 Agent Group Config 配置# 确认 Server 端配置是否更新 deepflow-ctl agent-group-config list $AGENT_GROUP_CONFIG_NAME -o yaml3. 查看 Agent 使用的 Server 真正下发的配置deepflow-ctl trisolaris.agent-check config \ --cip $AGENT_IP \ --cmac $AGENT_MAC \ --cid $DOMAIN_ID \ --gid $AGENT_GROUP_ID联系方式GitHub Issues: https://github.com/deepflowio/deepflow/issuesDeepFlow 开源社区群常见问题Q1: DeepFlow Agent 支持哪些操作系统DeepFlow Agent 支持主流的 Linux 发行版包括Ubuntu 18.04推荐 20.04CentOS 7 / RHEL 7Debian 10Fedora 30内核要求Linux 内核版本 ≥ 4.14推荐 5.x 以上以获得更好的 eBPF 支持。Q2: Agent 注册失败如何快速定位问题按以下顺序排查等待 5 分钟以上初始化需要时间检查 Domain 和 Agent Group Config 是否创建主机部署检查 Agent IP 是否在 Server 的local_ip_ranges内检查主机名是否重复检查是否通过 LB 连接 ServerQ3: 为什么某些 IP 在 Metrics 中显示为 0.0.0.0当 IP 不在 Server 的local_ip_ranges配置中时DeepFlow 会将其识别为广域网 IP在 Metrics 中聚合为0.0.0.0。将对应网段添加到local_ip_ranges配置中即可解决。在 Request Log 中可以通过is_internettruetag 确认该 IP 是否被识别为广域网。Q4: eBPF 加载失败怎么办eBPF 加载失败通常是因为内核版本不适配。请确认内核版本 ≥ 4.14推荐 5.x使用 show-kernel-struct-offset 工具收集信息将结果提交到 GitHub Issues 或 DeepFlow 社区群Q5: 如何启用 PostgreSQL/MongoDB 等非默认协议的解析通过agent-group-config配置文件添加processors: request_log: application_protocol_inference: enabled_protocols: - PostgreSQL - MongoDB保存后 Agent 会自动拉取新配置无需重启。Q6: K8s 集群中某些资源看不到是什么原因常见原因