基于eBPF的零插桩AI智能体观测：AgentSight内核级监控实战

1. 项目概述：当AI智能体遇上内核级观测

最近在折腾各种LLM智能体（Agent）时，我遇到了一个挺头疼的问题：这些家伙在后台到底干了啥？它们调用了哪些API？生成了什么文件？占用了多少资源？传统的应用层监控工具，比如给代码插桩（Instrumentation）或者用代理（Proxy），要么需要修改代码、引入依赖，要么在智能体使用非标准通信方式（比如直接调用系统命令、静态链接SSL库）时就抓瞎了。更别提那些闭源的商业AI工具了，内部运作完全是个黑盒。

就在我琢磨有没有一种“上帝视角”的观测方法时，我发现了AgentSight。这个项目彻底颠覆了我对应用监控的认知。它不跟你玩应用层的猫鼠游戏，而是直接下沉到操作系统内核，利用eBPF技术，在系统边界进行零侵扰的观测。简单来说，它就像一个安装在操作系统交通枢纽上的高清摄像头，无论路上跑的是Python脚本、Node.js应用还是静态编译的二进制怪兽，只要它们通过系统的“公路”（如SSL/TLS库、进程调度）进行通信，都能被清晰记录。

AgentSight的核心价值在于零插桩。你不需要在智能体代码里加一行日志，也不用配置复杂的中间件。它通过eBPF钩子（uprobe/tracepoint）直接拦截SSL/TLS的读写操作和进程生命周期事件，从而还原出智能体完整的交互图谱——从它发送的原始提示词（Prompt），到接收的流式响应，再到它触发的子进程和文件操作，一览无余。这对于开发、调试AI应用，尤其是进行安全审计和性能分析，简直是降维打击。

2. 核心原理深度解析：eBPF如何实现零插桩观测

要理解AgentSight为何强大，我们必须先搞懂eBPF（Extended Berkeley Packet Filter）是什么。你可以把它想象成一套嵌入Linux内核的、安全可控的“微型虚拟机”系统。它允许用户编写一些小程序（eBPF程序），在确保安全的前提下，将其注入到内核的特定执行点（如系统调用、网络事件、函数入口）运行。这些程序能够收集、过滤并转发内核空间的数据到用户空间，而这一切对上层应用几乎是透明的，性能开销极低。

2.1 传统观测的瓶颈与eBPF的破局点

传统应用监控（APM）就像给房子里的每个房间安装独立传感器。要监控一个新应用（新房间），你就得重新布线、安装传感器（插桩）。如果房主（应用）把传感器拆了或者关掉了，你就瞎了。而eBPF的思路是在房子的总水管、总电闸和主通道上安装传感器。无论房间里住的是谁，只要用水用电、进出走动，都逃不过监测。

具体到LLM智能体，它们与外界交互主要依赖几个核心系统调用和库函数：

1. 网络通信：几乎都通过SSL/TLS加密（如OpenSSL库的SSL_read/SSL_write函数）。
2. 进程管理：通过fork,execve等系统调用创建子进程来执行命令。
3. 文件系统：通过open,read,write等系统调用读写文件。

AgentSight的eBPF程序就精准地挂载在这些关键点上：

• SSL Monitor：通过uprobe（用户空间探针）挂载到目标进程的libssl.so库（或静态链接的SSL函数）中的SSL_read和SSL_write函数上。当智能体进行加密通信时，eBPF程序能在数据被加密前或解密后，直接读取到明文的请求和响应内容。
• Process Monitor：通过tracepoint（内核静态跟踪点）挂载到sched_process_fork,sched_process_exec等事件上。无论智能体调用什么命令，只要触发了进程创建或执行，都会被捕获。
• File Monitor：通过挂载到security_file_open等LSM（Linux安全模块）钩子或tracepoint，监控文件的打开和操作。

关键提示：uprobe需要知道目标函数的符号地址。对于动态链接libssl.so的应用，这很简单。但对于像Claude Code（基于Bun，静态链接BoringSSL）或某些NVM安装的Node.js（可能静态链接OpenSSL）的应用，符号表可能被剥离（stripped）。这时，AgentSight的--binary-path参数配合字节码模式匹配就派上用场了，它能在二进制文件中直接定位SSL函数。

2.2 数据流转与关联分析架构

仅仅捕获原始事件是不够的。一个AI智能体的行为可能是由一连串相关的网络请求、进程创建和文件操作组成的。AgentSight的巧妙之处在于其用户空间的Rust流式处理框架，它负责将孤立的内核事件关联成有意义的“会话”。

数据流转管道如下：

内核事件 (eBPF) -> 原始JSON流 -> Rust Runner (收集器) -> Analyzer Chain (分析链) -> 前端可视化/存储

1. Runners：负责加载和执行特定的eBPF程序（如sslsniff,process），并将内核产生的原始事件以JSON格式流式输出。
2. Analyzers：这是一系列可插拔的处理器，构成一个处理链（Chain）。每个Analyzer负责一项具体任务：
   • HTTP Parser：从SSL明文数据中解析出HTTP请求和响应头、体。
   • Chunk Merger：对于流式响应（如Server-Sent Events），将多个数据块合并为完整的消息。
   • Filter：过滤掉敏感信息（如Authorization头）或噪音数据。
   • Correlator：这是核心。它通过进程ID（PID）、线程ID、时间戳、网络五元组等信息，将来自不同eBPF程序的事件进行关联。例如，将一个Python进程发起的SSL请求，与其后续创建的git子进程事件关联起来，形成一个完整的“用户提问 -> AI生成代码 -> 执行代码”的轨迹。
3. 输出：处理后的、富含上下文信息的事件被发送到前端进行实时可视化，也可以存储到文件或日志系统。

这种架构使得AgentSight不仅能“看到”数据，还能“理解”数据流之间的关系，构建出智能体行为的动态图谱。

3. 实战部署与配置详解

理论讲完了，我们来点实际的。下面我将手把手带你完成AgentSight的部署，并针对几种典型的AI工具进行监控配置。我会解释每个参数背后的原因，并分享我踩过的一些坑。

3.1 环境准备与安装

首先，确保你的系统满足最低要求：

• Linux内核：4.1以上（推荐5.0+）。eBPF特性在不同内核版本有差异，越新的内核支持的特性越丰富、越稳定。用uname -r检查。
• 权限：需要root权限或具备CAP_BPF、CAP_SYS_ADMIN能力来加载eBPF程序。
• 依赖工具：clang,llvm,libelf-dev（用于编译eBPF程序），rustc（用于编译收集器）。

安装方式选择： 对于大多数想快速上手的用户，我强烈推荐Docker方式。它封装了所有复杂的依赖，并且通过容器隔离提升了安全性（毕竟eBPF权限很高）。

# 拉取最新的AgentSight镜像 docker pull ghcr.io/eunomia-bpf/agentsight:latest

Docker运行需要一些特殊的参数，我来逐一解释：

• --privileged：容器需要特权模式来加载eBPF程序到主机内核。
• --pid=host：让容器共享主机的进程命名空间，这样它才能看到并跟踪主机上所有进程。
• -v /sys:/sys:ro：以只读方式挂载/sys文件系统，eBPF程序需要从这里获取系统信息（如cgroup、挂载点）。
• -v /usr:/usr:ro -v /lib:/lib:ro：这是关键！以只读方式挂载/usr和/lib。因为uprobe需要挂载到主机上目标进程加载的共享库（如/usr/lib/x86_64-linux-gnu/libssl.so.1.1）。如果容器内没有这些库文件，eBPF程序将无法正确附加。
• --network=host：共享主机网络命名空间，方便前端UI绑定到主机端口。

3.2 监控Python AI工具（最简场景）

假设你正在开发或使用一个基于Python的AI助手，比如aider（代码助手）或open-interpreter（开放解释器）。这是最简单的情况，因为Python通常动态链接系统的OpenSSL库。

# 启动AgentSight容器，监控所有命令名（comm）为“python”的进程 docker run --name agentsight -d --privileged --pid=host --network=host \ -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \ -v $(pwd)/agent_logs:/logs \ ghcr.io/eunomia-bpf/agentsight:latest \ record --comm python --log-file /logs/record.log --server-port 8080

参数解析与避坑指南：

• --comm python：comm是进程的短名称（通常不超过16字符），由bpf_get_current_comm()获取。对于Python脚本，主进程的comm通常是“python”。这个过滤器只监控进程名为“python”的SSL和进程事件。
• --log-file /logs/record.log：将结构化日志输出到挂载的卷中，方便后续分析。
• --server-port 8080：将内置的Web服务器端口改为8080。默认是7395，如果冲突可以修改。
• -v $(pwd)/agent_logs:/logs：将主机当前目录下的agent_logs文件夹挂载到容器的/logs。这样日志文件就持久化在主机上了。

启动后，打开浏览器访问http://你的主机IP:8080，就能看到实时的时间线视图。现在，在另一个终端运行你的Python AI工具，所有的网络请求、子进程调用都会实时显示在Web界面上。

实操心得：comm过滤有时不够精确。如果系统中有多个不相关的Python进程，也会被捕获到。你可以通过--pid参数指定具体的进程ID，或者结合--parent参数监控特定父进程产生的子进程，来减少噪音。

3.3 监控静态链接的复杂应用：以Claude Code为例

Claude Code是一个典型挑战。它基于Bun运行时，并且将BoringSSL（Google的TLS库）静态链接到了二进制文件中，同时剥离了调试符号。这意味着：

1. 没有独立的libssl.so文件供uprobe挂载。
2. 我们不知道SSL_read/SSL_write函数在二进制文件中的具体地址。

AgentSight的解决方案是：通过--binary-path参数提供二进制文件路径，在内部使用字节码模式匹配（Pattern Matching）来定位SSL函数。

步骤分解：

1. 定位Claude二进制文件：Claude Code通常安装在用户目录下。

   # 首先，找到Claude的安装路径和版本 claude --version # 示例输出：2.1.39 # 二进制文件通常位于：~/.local/share/claude/versions/<version>/ CLAUDE_BIN=~/.local/share/claude/versions/$(claude --version | head -1) echo $CLAUDE_BIN # 确认路径，例如：/home/user/.local/share/claude/versions/2.1.39

2. 使用Docker运行监控：需要将Claude的二进制文件所在目录挂载到容器内。

   docker run --name agentsight-claude -d --privileged --pid=host --network=host \ -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \ -v $HOME/.local/share/claude:/claude:ro \ -v $(pwd)/claude_logs:/logs \ ghcr.io/eunomia-bpf/agentsight:latest \ record --comm claude --binary-path /claude/versions/2.1.39 --log-file /logs/record.log

   关键点：
   • -v $HOME/.local/share/claude:/claude:ro：将主机上的Claude安装目录只读挂载到容器的/claude路径下。
   • --binary-path /claude/versions/2.1.39：告诉AgentSight，目标二进制文件在容器内的这个路径。它会分析这个二进制文件，寻找SSL函数。
   • --comm claude：这里有一个重要细节。Claude Code的SSL流量实际上发生在一个名为“HTTP Client”的内部线程，而不是主“claude”线程。当你指定了--binary-path，AgentSight的收集器会自动忽略SSL监控的--comm过滤器，以确保能捕获到所有SSL流量。但--comm claude过滤器仍然会作用于进程监控部分，只跟踪由“claude”进程创建的进程树。

启动后，运行Claude Code进行操作，你将在Web UI上看到完整的API调用序列（如/v1/messages的POST请求和流式响应）、心跳包、甚至它内部的Datadog日志请求，以及它可能触发的任何文件或子进程操作。

3.4 监控Node.js应用（NVM环境）

通过NVM（Node Version Manager）安装的Node.js，有时会静态链接OpenSSL以提高可移植性。这带来了和Claude Code类似的问题。

# 假设你使用NVM，并且当前使用的Node版本是v20.0.0 NODE_BIN=~/.nvm/versions/node/v20.0.0/bin/node docker run --name agentsight-node -d --privileged --pid=host --network=host \ -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \ -v $(dirname $NODE_BIN):/node_bin:ro \ -v $(pwd)/node_logs:/logs \ ghcr.io/eunomia-bpf/agentsight:latest \ record --comm node --binary-path /node_bin/node --log-file /logs/record.log

解释：$(dirname $NODE_BIN)获取Node.js二进制文件所在的目录，然后将其挂载到容器。--binary-path指向容器内的路径。

对于使用系统包管理器（如apt）安装的Node.js，它通常动态链接libssl.so，那么直接使用--comm node即可，无需--binary-path。

4. 高级用法与场景拓展

掌握了基础监控后，AgentSight还有一些高级功能可以应对更复杂的观测场景。

4.1 组合监控与全局视图

如果你有一个由多个不同组件（Python服务、Node.js工具、二进制程序）构成的复杂AI智能体系统，你可以启动一个全局监控会话，然后通过过滤器在UI上聚焦。

# 启动一个同时监控SSL和进程事件的服务，不限制命令名（监控所有进程） docker run --name agentsight-global -d --privileged --pid=host --network=host \ -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \ -v $(pwd)/all_logs:/logs \ ghcr.io/eunomia-bpf/agentsight:latest \ trace --ssl true --process true --server true --server-port 9090

使用trace命令并设置--ssl true --process true会启用所有监控探针。Web UI（端口9090）提供了强大的过滤和搜索功能，你可以按进程名、PID、时间范围或事件类型（网络、文件、进程）来筛选，从而在庞杂的全局事件中定位到你关心的智能体行为。

4.2 浏览器内AI交互监控

有些AI应用以前端Web形式存在，用户与AI的交互发生在浏览器中。AgentSight提供了独立的browsertraceBPF工具来捕获浏览器进程内的明文通信（例如，通过WebSocket或Fetch API与后端服务通信）。

# 假设你已经从源码构建了项目 cd agentsight # 监控Chrome浏览器 sudo ./bpf/browsertrace --binary-path /opt/google/chrome/chrome # 监控Firefox (注意：Ubuntu Snap安装的Firefox，其二进制文件在特殊路径) sudo ./bpf/browsertrace --binary-path /snap/firefox/current/usr/lib/firefox/firefox

注意：browsertrace的原理同样是uprobe，它需要附加到浏览器进程的SSL/TLS读写函数上。因此，你需要提供正确的、未被包装的浏览器二进制文件路径。在Ubuntu上，/usr/bin/firefox往往是一个启动脚本，真正的二进制在Snap目录下。

4.3 本地MCP（Model Context Protocol）服务器监控

MCP是一种新兴的协议，允许AI模型与外部工具和数据进行安全通信。一些本地MCP服务器通过stdio（标准输入输出）与AI客户端通信，而不是HTTP。对于这种场景，AgentSight提供了stdiocap工具。

# 首先，找到你的本地MCP服务器的进程ID (PID) ps aux | grep your-mcp-server # 假设PID是 12345 sudo ./bpf/stdiocap -p 12345

stdiocap会捕获该进程的stdin、stdout和stderr上的所有数据流，让你能看到AI模型和MCP服务器之间交换的原始JSON-RPC消息。

5. 问题排查与性能调优

即使工具强大如AgentSight，在实际部署中也可能遇到问题。下面是我总结的一些常见故障和解决方法。

5.1 权限问题与能力集

问题：运行命令时出现Operation not permitted或Permission denied。原因：加载eBPF程序需要特权。Docker方式使用了--privileged，已解决。如果是宿主机直接运行二进制，必须使用sudo。解决：

• 始终使用sudo运行./agentsight命令。
• 对于生产环境，可以考虑配置细粒度的Linux能力（Capabilities），如赋予二进制文件CAP_BPF和CAP_SYS_ADMIN能力，而非完全使用root。但这需要更复杂的安全评估。

5.2 eBPF程序加载失败

问题：启动时提示Failed to load BPF program或invalid argument。原因与排查：

1. 内核版本过低：确认内核版本 >= 4.1。某些eBPF特性（如BTF）需要更高版本。

   uname -r

2. 内核配置不支持：eBPF需要内核编译时启用相关选项。可以检查：

   zgrep -i BPF /proc/config.gz 2>/dev/null || cat /boot/config-$(uname -r) | grep -i BPF

   确保CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_JIT=y等已启用。
3. 头文件不匹配：eBPF程序编译依赖内核头文件。如果使用源码编译，在非标准内核或自定义内核上，可能需要手动生成或更新vmlinux.h文件。Docker镜像通常包含了通用头文件，问题较少。

5.3 捕获不到SSL流量

问题：Web UI上能看到进程事件，但看不到任何网络请求/响应。原因与排查（按可能性排序）：

1. 目标进程使用静态链接SSL库：这是最常见原因。检查你的应用（如Claude Code, 特定方式安装的Node.js）是否静态链接了SSL。使用ldd命令检查：

   ldd /path/to/your/binary | grep ssl

   如果输出中不包含libssl.so，而是显示not a dynamic executable或没有ssl库，那就是静态链接。必须使用--binary-path参数。
2. --comm过滤器不匹配：SSL流量可能发生在非主线程。如前所述，对于指定了--binary-path的应用，收集器会忽略SSL的comm过滤。但如果你没指定--binary-path，且--comm设置错误，就会漏掉。尝试不加--comm过滤，看是否能捕获到流量。
3. SSL库版本或函数名差异：AgentSight的uprobe默认挂钩SSL_read和SSL_write。一些应用可能使用不同名称的函数（如BoringSSL的BIO_read/BIO_write）。AgentSight的字节码模式匹配会尝试处理常见变体。如果怀疑是此问题，可以尝试运行sslsniff工具并开启--verbose模式，查看其识别出了哪些函数。

   sudo ./bpf/sslsniff --binary-path /path/to/binary --verbose

4. 流量本身不是SSL/TLS：确认你的AI工具是否真的在使用HTTPS/WSS。有些本地工具可能使用纯HTTP或自定义协议。

5.4 性能开销评估与优化

AgentSight宣称性能开销低于3%。在我的测试中（Ubuntu 22.04, Kernel 6.2，监控一个频繁调用API的Python脚本），使用perf和bpftool观察，CPU使用率增加大约在1-2%之间，内存开销主要来自用户空间的Rust收集器和前端，约几十MB。

如果发现开销较大，可以考虑以下优化：

1. 缩小监控范围：使用更精确的--pid或--parent过滤器，而不是宽泛的--comm。
2. 调整采样率：目前AgentSight似乎没有提供内置的采样率配置。但你可以修改eBPF源码，在事件触发逻辑中加入采样逻辑（例如，每N个事件上报一个），然后重新编译。这需要一定的eBPF开发知识。
3. 禁用不需要的探针：如果只关心网络流量，使用--ssl true --process false。如果只关心进程树，则反之。
4. 优化前端数据量：Web UI实时渲染大量事件可能消耗客户端资源。可以定期清理或导出日志，关闭不必要的实时更新。

5.5 数据安全与隐私考虑

警告：AgentSight能捕获SSL明文，这意味着它能看到包括认证令牌（API Keys）、敏感提示词和响应在内的所有数据。

最佳实践：

1. 仅在受控环境使用：绝对不要在共享服务器或生产环境未经授权使用。
2. 使用内置过滤器：AgentSight的Analyzer链包含过滤器，可以在数据进入日志或前端前，脱敏敏感信息（如将Authorization: Bearer sk-...替换为Authorization: [FILTERED]）。确保这些过滤器被启用和正确配置。
3. 安全存储日志：将--log-file指向加密的存储卷，并设置严格的访问权限。
4. 及时清理：分析完成后，及时停止AgentSight并删除包含敏感数据的日志文件。

6. 从观测数据到深度洞察：分析与应用

捕获到数据只是第一步，如何从中提取有价值的信息才是关键。AgentSight的Web UI提供了三个核心视图，帮助你进行分析：

1. 时间线视图：以时间轴形式展示所有事件（网络请求、进程生成、文件操作）。你可以清晰地看到事件的因果关系，例如：一个网络请求后，紧接着触发了一系列文件读写和子进程执行。
2. 进程树视图：可视化展示进程间的父子关系。这对于理解智能体如何通过“链式思考”调用多个工具（例如，先调用Python脚本，该脚本又调用shell命令）非常有帮助。你可以一眼看出整个执行链条的根进程和所有后代。
3. 原始日志视图：提供经过分析器处理后的结构化JSON日志。这是进行深度分析、自定义脚本处理或导入到其他系统（如Elasticsearch）的基础。

实际应用场景举例：

• 调试智能体幻觉：AI有时会“幻觉”出不存在的API或命令。通过观察时间线，你可以确认智能体是否发送了错误的请求，或者是否错误地解析了响应，从而导致了后续的失败操作。
• 性能瓶颈分析：观察网络请求的延迟、进程执行的耗时。如果发现某个工具调用特别慢，可以定位到具体是网络问题还是工具本身执行慢。
• 安全审计：监控智能体是否有未授权的文件访问、网络连接或命令执行。特别是当智能体具备“代码解释器”或“shell访问”权限时，这种监控至关重要。
• 成本优化：统计智能体调用不同API端点的频率和消耗的token数，为API使用成本优化提供数据支持。

我个人在集成多个AI工具的工作流中，通过AgentSight发现了一个隐蔽的问题：某个工具在失败后会不断重试同一个有问题的网络请求，导致大量不必要的token消耗和延迟。如果没有这种系统级的观测，仅凭应用日志很难发现这种循环行为。

最后，再分享一个小技巧：对于长期运行的监控任务，可以考虑将AgentSight的日志输出（--log-file）配置为对接像Vector或Fluentd这样的日志收集器，然后导入到Grafana或Kibana中，搭建一个长期的、可查询的智能体行为观测平台。这样，你不仅可以实时监控，还能对历史行为进行趋势分析和异常检测。