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

目录

1. 前言

1.1 适用范围

本文档适用于 DeepFlow Agent v6.5 及以上版本。

1.2 运行权限及内核要求

确保环境满足运行权限及内核要求。

1.3 排查前检查

检查项 要求
版本 Agent/Server 为 LTS 版本，且 Agent ≤ Server 版本
部署方式 主机进程部署 或 K8s Pod 部署
工具 已安装与 Server 同版本的 deepflow-ctl
等待时间 Agent 部署后等待 5 分钟以上再排查（初始化需要时间）
网段 Agent IP 在 Server 的 local_ip_ranges 网段内

2. 部署问题排查

2.1 主机进程部署

主机进程部署通过 deepflow-agent 二进制直接运行在主机上，默认使用 38086 端口。

Agent 注册失败排查

按以下顺序检查：

  1. 检查 Domain 与 Agent Group Config 配置
  2. 检查 Server 网段配置
  3. 检查主机名是否重名
  4. 检查是否通过 LB 连接 Server
2.1.1 检查 Domain 与 Agent Group Config 配置

主机进程部署需要完成两个步骤：

  1. 创建 Host Domain（类型为 agent_sync）
  2. 创建 Agent Group Config（采集器组配置）

这两个步骤缺一不可。agent_sync 类型 Domain 只能创建一个，多了会导致注册异常。

排查步骤：

  1. 检查 Host Domain 是否已创建：
# 确认列表中存在类型为 agent_sync 的 Domain
deepflow-ctl domain list
  1. 检查 Agent Group Config 是否已创建：
deepflow-ctl agent-group-config list

解决方案：

如果缺少 Host Domain：

unset DOMAIN_NAME
DOMAIN_NAME="legacy-host" # 修改为实际的 domain 名称

cat << EOF | deepflow-ctl domain create -f -
name: $DOMAIN_NAME
type: agent_sync
EOF

Domain 用于让 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 不在该配置范围内，会导致：

  1. Agent 无法正常注册
  2. 某些 IP 在 metrics 中被聚合为 0.0.0.0（广域网 IP）

排查步骤：

  1. 获取 Agent 的 IP 地址
  2. 检查 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 展示 说明
Metrics 0.0.0.0 聚合为广域网 IP
Request Log 真实 IP 保留原始 IP

判断方法：在 Request Log 面板中通过 is_internet tag 判断，值为 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 完成注册

排查步骤：

  1. 确认所有 Pod 状态正常：
kubectl get pods -n deepflow

所有 Pod 应处于 Running 状态。

  1. 等待 5-6 分钟后检查 Agent 注册状态：
deepflow-ctl agent list

在 K8s 部署中，Agent Pod 的 ConfigMap 中 Server 地址配置为 Server Service Name。由于 Server 和 Agent 在同一集群内，网络连通性一般不会有问题。注册未完成通常是因为初始化未完成，等待即可。

  1. 如果等待 5 分钟后仍未注册成功，尝试重启 Agent Pod：
kubectl delete pods -n deepflow -l app=deepflow-agent

注意事项：

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 下没有任何 Pod
Service Service 没有关联任何 Pod
Pod Pod 没有上层资源（如 Deployment、DaemonSet、StatefulSet），仅为单独的 Pod

DeepFlow 认为没有完整上下层关系的资源没有展示意义。

排查方法：

  • 检查资源是否有关联的上下层资源
  • 确认 Pod 是否通过控制器（Deployment/DS/STS）创建

3. 资源不是 K8s 原生资源

如果资源是通过自定义 Operator 创建的（非 K8s 原生 Kind），DeepFlow 可能无法正确识别其上层资源关系。

示例：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: 30033

3.2 缺少协议数据

DeepFlow 支持多种应用层协议解析，但 v6.5 版本后，为了降低资源开销，Agent 默认仅解析以下协议：

  • HTTP
  • HTTP2/gRPC
  • MySQL
  • Redis
  • Kafka
  • DNS
  • TLS

其他协议需要手动启用，例如：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: EbpfRunningError

eBPF 加载失败是因为 DeepFlow 对当前使用的系统或内核版本不适配。

解决方案：

情况一：使用通用操作系统

如果你使用的是通用操作系统（Ubuntu、CentOS、Debian、Fedora 等），按以下步骤收集信息并反馈给社区：

  1. 查看内核版本：
uname -a
hostnamectl
  1. 运行内核结构偏移量检查工具：

使用 show-kernel-struct-offset 项目：

# 下载并编译工具
git clone https://github.com/deepflowio/show-kernel-struct-offset.git
cd show-kernel-struct-offset
make
  1. 将结果发送到 DeepFlow 社区：
  • 在 GitHub Issues 中提交
  • 或发送到 DeepFlow 开源社区群

社区会根据提供的信息适配对应的内核版本。

情况二：使用自定义系统或内核

如果你使用的是自定义操作系统或内核，需要自行适配：

参考 PR 示例：自定义内核适配示例

前提条件检查：

在排查 eBPF 问题时，先确认环境满足要求：

运行权限及内核要求

3.4 配置识别异常

可能的原因：

  1. 配置下发延迟或失败
  2. Agent 未正确识别 Server 下发的配置
  3. 配置格式错误导致解析失败
  4. Agent 版本不支持该配置项

排查步骤：

1. 查看组件版本

# 查看 Agent commit 版本
deepflow-agent -v

# 查看 Server commit 版本
deepflow-server -v

2. 查看 Agent Group Config 配置

# 确认 Server 端配置是否更新
deepflow-ctl agent-group-config list $AGENT_GROUP_CONFIG_NAME -o yaml

3. 查看 Agent 实际识别的配置

deepflow-ctl trisolaris.agent-check config \
  --cip $AGENT_IP \
  --cmac $AGENT_MAC \
  --cid $DOMAIN_ID \
  --gid $AGENT_GROUP_ID

联系方式：

常见问题

Q1: DeepFlow Agent 支持哪些操作系统？

DeepFlow Agent 支持主流的 Linux 发行版，包括：

  • Ubuntu 18.04+（推荐 20.04+）
  • CentOS 7+ / RHEL 7+
  • Debian 10+
  • Fedora 30+

内核要求：Linux 内核版本 ≥ 4.14，推荐 5.x 以上以获得更好的 eBPF 支持。

Q2: Agent 注册失败如何快速定位问题？

按以下顺序排查：

  1. 等待 5 分钟以上（初始化需要时间）
  2. 检查 Domain 和 Agent Group Config 是否创建（主机部署）
  3. 检查 Agent IP 是否在 Server 的 local_ip_ranges 内
  4. 检查主机名是否重复
  5. 检查是否通过 LB 连接 Server

Q3: 为什么某些 IP 在 Metrics 中显示为 0.0.0.0？

当 IP 不在 Server 的 local_ip_ranges 配置中时，DeepFlow 会将其识别为广域网 IP，在 Metrics 中聚合为 0.0.0.0。将对应网段添加到 local_ip_ranges 配置中即可解决。

在 Request Log 中可以通过 is_internet=true tag 确认该 IP 是否被识别为广域网。

Q4: eBPF 加载失败怎么办？

eBPF 加载失败通常是因为内核版本不适配。请：

  1. 确认内核版本 ≥ 4.14（推荐 5.x+）
  2. 使用 show-kernel-struct-offset 工具收集信息
  3. 将结果提交到 GitHub Issues 或 DeepFlow 社区群

Q5: 如何启用 PostgreSQL/MongoDB 等非默认协议的解析？

通过 agent-group-config 配置文件添加：

processors:
  request_log:
    application_protocol_inference:
      enabled_protocols:
        - PostgreSQL
        - MongoDB

保存后 Agent 会自动拉取新配置，无需重启。

Q6: K8s 集群中某些资源看不到是什么原因？

常见原因：

  1. 没有流量：资源从未有请求/响应
  2. 孤立资源：Pod 没有上层控制器（Deployment/DS/STS）
  3. 非原生资源：通过自定义 CRD 创建，DeepFlow 无法识别

Q7: Agent 和 Server 版本有什么要求？

Agent 版本必须 ≤ Server 版本。建议使用 LTS 版本，非 LTS 版本请升级后再排查问题。

相关资源

文档版本：v1.1
最后更新：2026-03-18
适用版本：DeepFlow Agent v6.5+

posted @ 2026-03-19 10:17  怎么还在写代码  阅读(39)  评论(0)    收藏  举报