feat: support agent governance

[kylewanginchina]

This PR is for:

• Agent
• Server

Support agent governance

• Code Change Description
• 
• 

Checklist

• Added unit test.

Backport to branches

[lzf575]

ingest 部分没问题

[xiaochaoren1]

translation.go 部分，只在 INT_ENUM_PEER_TAG 里加一下即可，其他地方不用改

[kylewanginchina]

translation.go 部分，只在 INT_ENUM_PEER_TAG 里加一下即可，其他地方不用改

@xiaochaoren1 意思是下图中红框的部分不需要，只需要在 INT_ENUM_PEER_TAG中加一下biz_type？

下面是codex的回复意见：

[kylewanginchina]

关于gprocess_id的情况说明：

进程启动初期，如果调用/v1/chat/completions以及执行文件操作等，gprocess_id会有一段时间为0，光process表有数据还不行，得等platformInfoTable那边缓存同步（周期是60s）了才会让gprocess_id正常，也就是gprocess_id会少关联一部分进程初始阶段的llm请求log以及操作事件。

目前遗留问题：

1. 无限量流重组支持上还存在问题

[kylewanginchina]

AI Agent Governance

背景

这组改动为 AI Agent / 智能体治理补齐了从 识别、进程归属、治理事件采集、数据落库 到
查询暴露 的完整链路，目标是让 reviewer 能够明确回答下面 5 个问题：

1. DeepFlow 如何识别一个进程是 AI Agent。
2. AI Agent 的 biz_type、root_pid、gprocess_id 如何在子进程 / 孙进程场景下保持稳定。
3. 哪些治理事件会被采集，以及它们最终落到哪些表。
4. 上层查询如何拿到这些字段与表。
5. 为了让这套能力可上线，过程中修了哪些正确性、兼容性和噪声问题。

变更范围

deepflow（开源侧）

• 53 commits
• 120 files changed
• 3998 insertions
• 174 deletions

deepflow-core（EE / 联动依赖侧）

• 28 commits
• 25 files changed
• 1754 insertions
• 688 deletions

Reviewer Guide

建议按下面顺序评审，这样最容易建立全局上下文：

1. AI Agent 配置与识别
   • 看 AI Agent 配置项是如何引入的
   • 看 HTTP parser 如何命中 AI endpoint
   • 看 http_endpoint_disabled 与 AI endpoint 的关系
2. AI Agent 注册表与进程归属
   • 看 EE 侧 AiAgentRegistry
   • 看 child / thread / exec / proxy 场景如何处理
   • 看 root_pid / biz_type 如何稳定传播
3. eBPF 与 ProcEvent 数据面
   • 看 file I/O、file meta、permission、proc lifecycle 事件是怎么采的
   • 看 ProcEvent protobuf 是如何扩展的
4. Server 落库与新事件表
   • 看 decoder 如何路由事件
   • 看 4 张新表的字段与 reducer 逻辑
   • 看 .1s/.1s_mv 聚合为什么要关闭
5. Querier 暴露与数据源接入
   • 看新的 metrics / tag descriptions
   • 看 gprocess.biz_type 查询翻译
   • 看 data_source 默认记录注册
6. 收尾修复
   • 看 reviewer feedback 修复
   • 看 multi-controller / non-Linux / log noise / build warning 等兼容性处理

核心修改说明

1. 新增 AI Agent 配置与识别入口

这一部分的目标，是让 AI Agent 成为一个可配置、可识别、可调参的能力，而不是写死在解析器里的特殊分
支。

主要变化：

• 新增 inputs.proc.ai_agent 配置树，支持：
  • http_endpoints
  • max_payload_size
  • file_io_enabled
• 在 HTTP parser 中增加 AI endpoint 命中逻辑，命中后可把对应进程标记为 AI Agent。
• 默认 endpoint 覆盖常见 OpenAI 风格 API，包括：
  • /v1/chat/completions
  • /v1/embeddings
  • /v1/responses
• 修正了 http_endpoint_disabled=true 时 AI Agent 识别被误关掉的问题。
  • 现在普通 http_endpoint 提取开关只控制普通 endpoint 逻辑，不再屏蔽 AI endpoint 识别。

review 价值：

• 这一组提交定义了“什么叫 AI Agent”。
• 后续所有 biz_type、root_pid、治理事件，都是建立在这一步识别成功之上的。

---

2. 引入 EE 侧 AiAgentRegistry，稳定管理 AI Agent 进程状态

这一部分的目标，是把 AI Agent 的“注册 / 查询 / BPF map 同步 / 继承 / 回溯”从临时逻辑提升为一个稳定
的注册表能力。

主要变化：

• 在 deepflow-core/agent/crates/enterprise-utils 中实现 AiAgentRegistry。
• 支持：
  • 注册 / 查询 AI Agent PID
  • 同步到 BPF map
  • child 进程继承
  • thread fork 继承
  • root_pid 跟踪
  • 后续 endpoint hit 时重新对齐状态
  • 根据 socket role 区分真实 AI Agent 与代理进程
• 在 open-source 侧补了 stub，保证不开 enterprise feature 时也能编译。

review 价值：

• 这一组提交决定了 AI Agent 状态是不是“临时命中一次就丢”，还是“能被进程树稳定继承和追踪”。
• 也是 child / grandchild / exec 场景能够稳定归属的基础。

---

3. 将 AI Agent 的 biz_type 沿进程同步链路贯通

这一部分的目标，是让“AI Agent 身份”不只存在于 agent 运行时，而是进入 controller / process /
gprocess / querier 的统一元数据体系。

主要变化：

• 新增 BIZ_TYPE_AI_AGENT 常量。
• 在 agent 侧进程同步结构中加入 biz_type。
• 在 gRPC 消息中加入 biz_type：
  • message/agent.proto::ProcessInfo.biz_type
  • message/controller.proto::GenesisSyncProcess.biz_type
• 在 MySQL schema 中增加：
  • genesis_process.biz_type
  • process.biz_type
  • ch_gprocess.biz_type
• 在 process / gprocess 同步链路中保持 biz_type 的传播。
• 在 multi-controller 场景下修复 gprocess biz_type 同步。
• 在 querier 中增加 gprocess.biz_type 的查询翻译，并把相关 biz_type 展示改为枚举语义。

review 价值：

• 这组提交让 AI Agent 身份从“运行时判定结果”变成“可查询、可关联、可审计”的元数据。
• reviewer 可以重点看：
  • 标记何时写入
  • controller 何时保存
  • querier 如何暴露

---

4. 放宽 AI Agent 数据采集限制，保证大模型流量与治理数据可见

这一部分的目标，是避免 AI Agent 流量因为普通流量的限制策略而采集不完整。

主要变化：

• AI Agent 流量不再受普通 reassembly 限制。
• 协议推断完成后可以启用 reassembly。
• 对已经存在的 socket，在协议推断后也能重新启用 reassembly。
• 修复了 invalid socket info 场景下的 reasm bytes 问题。
• 将 reasm_bytes 继续向后透传到 eBPF merge / 下游逻辑。
• 子进程 file I/O 事件不再被 collect_mode 错误过滤。

review 价值：

• 如果这部分不成立，后面的 AI endpoint 命中、大 payload、文件治理事件很容易“不识别”或“只采到一
  半”。

---

5. 扩展 eBPF / ProcEvent 数据面，覆盖治理事件

这一部分的目标，是让 AI Agent 治理不只看到“请求了什么”，还要看到“文件做了什么、权限怎么改了、进程
怎么派生了”。

主要变化：

• raw file I/O 增加 access_permission。
• 扩展 message/metric.proto：
  • IoEventData.access_permission
  • EventType.FileOpEvent
  • EventType.PermOpEvent
  • EventType.ProcLifecycleEvent
  • FileOpEventData
  • PermOpEventData
  • ProcLifecycleEventData
  • ProcEvent.file_op_event_data
  • ProcEvent.perm_op_event_data
  • ProcEvent.proc_lifecycle_event_data
  • ProcEvent.ai_agent_root_pid
• 增加 / 对齐的 hook 包括：
  • file create / delete / chmod / chown
  • setuid / setgid / setreuid / setregid
  • fork / exec / exit
• 修复治理事件输出接入 __socket_data pipeline 的格式兼容性。
• 统一 file op 输出结构，便于 server 侧按统一模型解码。

review 价值：

• 这组提交定义了“治理事件的数据合同”。
• reviewer 可重点看：
  • BPF event payload 与 protobuf 是否一一对应
  • 事件含义是否足够支撑审计和进程树展示

---

6. 新增治理事件拆表与聚合逻辑

这一部分的目标，是把治理事件从原始 file_event 中拆分出来，减少噪声、提升可查询性。

主要变化：

• 保持原始 event.file_event 不变，继续写 raw read/write。
• 新增 4 张事件表：
  • event.file_agg_event
  • event.file_mgmt_event
  • event.proc_perm_event
  • event.proc_ops_event
• file_agg_event
  • 将连续相同的 raw read/write 聚合为 1 行
  • 聚合 key 显式包含 agent_id + root_pid + gprocess_id
  • 同时带上 path / permission / thread / coroutine 等维度，避免误聚合
• file_mgmt_event
  • 承载 create / delete / chmod / chown
  • 对重复 create 噪声做生命周期内去重
  • 去重 key 显式包含 agent_id + root_pid + path
• proc_perm_event
  • 承载权限变化前后值
• proc_ops_event
  • 承载 pid / parent_pid / root_pid / uid / gid / cmdline / exec_path
  • 支持上层按父子关系恢复进程树

review 价值：

• 这部分是治理数据“可用性”的核心。
• reviewer 重点看：
  • 为什么保留 raw 表
  • 为什么要拆 4 张表
  • reducer key 是否足够隔离不同 agent / gprocess

---

7. 修复 gprocess_id 在 AI Agent 子孙进程场景下的稳定性

这一部分的目标，是解决 AI Agent 根进程、子进程、孙进程、exec 之后的进程在事件落库时容易拿不到正确
gprocess_id 的问题。

主要变化：

• 在 agent 侧事件中加入 ai_agent_root_pid。
• server decoder 增加 root pid cache。
• resolveGProcessID() 增加多级 fallback：
  • 先查当前 pid
  • 再查 cached root pid
  • 再查 ai_agent_root_pid
  • lifecycle 事件再回退到 parent_pid
• 修复 child / grandchild / exec 场景下的 gprocess 继承。
• 修复 proc lifecycle 事件的 bytes / fallback 细节问题。

review 价值：

• 如果这部分不成立，新表里的事件会出现大量 gprocess_id=0 或归属错乱。
• 也是 root_pid 真正能落到治理视图中的关键。

---

8. 完善查询层、默认数据源与可观测性元数据

这一部分的目标，是让新数据“真正能被查到”，而不是只写进去。

主要变化：

• 为 4 张新表注册默认 data_source。
• 为 4 张新表补齐 querier metrics descriptions。
• 为 4 张新表补齐 tag descriptions（含中英文）。
• 新增 biz_type 枚举描述。
• 支持 gprocess.biz_type 标签查询。
• 新增 deepflow-ctl 对 AI Agent process show 的调试支持。

review 价值：

• 这部分决定了 reviewer / 用户是否能在上层正确看到新数据。
• 如果只改写入层、不补 query metadata，这个 PR 的一半价值会丢掉。

---

9. review / 环境验证驱动的可靠性修复

这一部分的目标，是把功能从“能跑”提升到“能上线”。

主要变化：

• 修复：
  • borrow / import / unused variable
  • null statement / macro injection / tracepoint 对齐
  • BPF stack usage / pid_tgid 使用
  • socket_trace 中遗漏的 AI Agent 判断
  • proc scan hook 跨平台编译告警
• 调整：
  • log level
  • sync log noise
  • registry / BPF map sync debug logs
• 清理：
  • 过时 stub
  • 简单 endpoint 唯一性约束（为 root_pid/socket role 方案让路）
• 关闭 4 张新表的 1-second aggregation，避免 .1s/.1s_mv 创建失败。
• 将 reducer 作用域进一步限制到 agent + gpid。

review 价值：

• 这些提交虽然很多是 fix/chore，但直接决定了这套能力是否可维护、可构建、可部署。

对 reviewer 的关注点

功能正确性

• AI Agent 识别是否只在期望 endpoint 命中时触发。
• http_endpoint_disabled 下 AI Agent 是否仍然成立。
• 代理进程是否会被 socket role 正确降级。
• child / thread / exec / grandchild 场景下 root_pid 与 gprocess_id 是否稳定。

数据一致性

• biz_type 是否从 agent 一路同步到 process / ch_gprocess / querier。
• ProcEvent 新字段是否在 agent、message、server 三端一致。
• 新增 4 张事件表的字段、metrics、tag descriptions 是否完整对齐。
• reducer key 是否足够避免跨 agent / 跨 gprocess 误聚合。

运维与兼容性

• open-source stub 是否保证非 EE 构建不受影响。
• non-Linux build 是否已 guard。
• .1s aggregation 关闭后是否满足查询需求。
• 日志噪声是否可控。

已验证

Go tests

• querier/engine/clickhouse/tag
• querier/engine/clickhouse/metrics
• ingester/event/common
• ingester/datasource
• ingester/event/decoder
• ingester/event/event
• ingester/event/dbwriter
• controller/http/service

Rust tests

• cargo test --package deepflow-agent proc_lifecycle

环境验证

• 4 张新表创建 / 重建 / 查询通过
• file_mgmt_event create 噪声压缩通过
• .1s/.1s_mv 不再为新表创建
• root_pid 字段替换已生效
• file_agg_event 聚合作用域已收敛到 agent + root_pid + gprocess_id

[lzf575]

ingester 写入正常。目前看新增加的几个 event 表，支持单独设置保留时长，后续需要在页面验证确认下。

[yinjiping]

ai_agent 不受io_event的配置控制，这里存在一个需要注意的问题：

• 如果文件读写是微秒甚至纳秒级别，file读写事件可能会非常非常多，吃掉节点资源，所以这里是否需要一个ai_agent 文件读写的时间限制更好一些？

[kylewanginchina]

这个担忧我确认过，但本轮不按“增加时间限制/限流”修改。PRD 在智能体数据采集里明确要求“所有文件读写事件，无需对读写时延、读写时机做限制”，功能测试用例里也有 TC-EVT-001/002/003/004 对应覆盖。因此这里不能通过在 BPF 层增加时延门槛或限流来处理。后续如果需要控制资源，只能走不改变事件可见性的优化路径，例如更强聚合、传输/存储优化或统计告警。

[yinjiping]

datadump 部分

deepflow/agent/src/ebpf/user/socket.c

Line 3784 in 010323c

" CONTAINER_ID %s SOURCE %d COMM %s " \

SOURCE 目前只是数值标识，如果可以的话可以显示具体的事件名称。

[kylewanginchina]

这个建议合理，属于调试可读性优化。我先记录为后续增强项，本轮优先处理 correctness 和语义一致性问题。

[yinjiping]

第637行已经上报了一个事件，可以评估将 AI 相关事件进行合并处理，以进一步降低事件数量。

当前 eBPF 侧的优化目标是控制系统开销，已围绕减少 Hook 点、精简事件上报、优化 Map 使用等方面持续推进，以降低对节点和业务负载的影响。

[kylewanginchina]

这个建议我先不在当前 PR 里改代码，原因是这里存在两条职责不同的事件链路：\n\n1. uprobe_base.bpf.c 里的通用 process_event_t（exec/exit）仍然被现有 Go/SSL uprobes 生命周期处理依赖；\n2. AI Agent 的 proc_ops_event 是额外治理数据通路。\n\n当前第 637 行上报的不是“只给 AI 用的重复事件”，直接合并掉会影响已有 proc event 消费者，所以这里不能简单在当前 PR 里做 BPF 侧合并。\n\n如果后续要进一步降事件量，我倾向于单独做一轮优化，把通用 proc_event 消费链和 AI governance 事件链一起梳理清楚，再决定是在 eBPF 侧去重、还是在用户态/ingester 侧聚合，避免引入现有 uprobes 生命周期回归。

[yinjiping]

当前 config_probes_for_proc_event 中已经覆盖了 sched_process_fork / exec / exit 三类核心进程事件。从进程生命周期角度看，这些 tracepoint 基本可以满足绝大部分场景需求。

如果仅关注进程创建、执行和退出行为，是否复用该处 hook 点就可以了？无需额外增加新的探针以及重复添加探针，从而有助于控制 eBPF 事件规模与系统开销。

[kylewanginchina]

这个点成立，我确认后会在当前 PR 里做最小修正。\n\nconfig_probes_for_proc_event() 已经注册了 exec/exit 生命周期 hook，而 config_probes_for_ai_agent() 又额外追加了同样的 sched_process_exec / sched_process_exit tracepoint；当前 tps_set_symbol() 只是追加，不做去重，所以这里确实属于重复注册。\n\n不过 sched_process_fork 不能一起删，因为 AI Agent 的子进程继承/传播逻辑是在 AI 专用 process_fork tracepoint 里做的，通用 proc_event 路径不能替代这部分。\n\n我这边会按这个边界处理：删掉 AI 部分重复的 exec/exit，保留 fork。

[kylewanginchina]

已按这个边界处理。\n\n当前改动是：\n1. 从 config_probes_for_ai_agent() 去掉重复的 sched_process_exec；\n2. 从 config_probes_for_ai_agent() 去掉重复的 sched_process_exit；\n3. 保留 sched_process_fork，继续负责 AI Agent 子进程继承/传播。\n\n这样通用 proc_event 路径继续负责 exec/exit 生命周期 hook，AI 专用路径只保留 fork 所需的额外 hook。\n\n我已在 builder 容器里做过 cargo check --features enterprise，编译通过。

[kylewanginchina]

补充说明一下，这里当前的实现前提已经变成“只支持 gprocess.biz_type tag 查询，不再支持裸 biz_type tag 查询”。在这个前提下，只在 INT_ENUM_PEER_TAG 里加一项已经不够了。

原因是 INT_ENUM_PEER_TAG 适用于底层存在真实 peer 字段的 enum tag，但 gprocess.biz_type_0/_1 不是物理列，它需要通过 gprocess_id_0/_1 -> flow_tag.gprocess_map.biz_type 做专门翻译。如果只加到 INT_ENUM_PEER_TAG，会把 Enum(gprocess.biz_type_0/_1) 走成直接读取不存在字段的通路，而且会覆盖掉专门的 translator。

所以当前修正做法是：

1. 保留 translation.go 里的 gprocess.biz_type 专用 translator；
2. 在相关表的 db_descriptions 中补 gprocess.biz_type 的 tag 描述，让 show tags / show tag values / Enum() / where filter 都能一致工作；
3. 裸 biz_type 回退为普通 int 字段，不再作为独立 tag 查询入口。

我已经按这个逻辑在当前分支验证过，file_event / file_agg_event / file_mgmt_event / proc_ops_event / proc_perm_event / l7_flow_log 上的 gprocess.biz_type 查询和枚举值查询都能正常工作。