skywalking-ai-sessionizer

这是什么？适合谁？

Apache SkyWalking AI Sessionizer（apache/skywalking-ai-sessionizer）是 Apache 官方子项目，提供面向长生命周期 AI Agent 的会话级可观测性（conversation-level observability）：测量与导出。

Agent 运行时会把一个用户可见的「对话」记录成一堆互不相干的产物——transcript、trace、日志、provider 请求体、工具事件、子 Agent 元数据。这段对话可能跨进程存活、空闲很久后再次激活、还包含多条并发的 Agent 执行线。仅靠 trace 级检查无法回答：整个对话做了什么？哪一次输入 / 模型响应 / 工具结果 / 子 Agent 结果导致了下一个模型调用？那次调用是延续了历史还是开了新上下文？哪些 Agent 参与其中？该把什么作为一个整体来测量、存储和导出？

SkyWalking AI Sessionizer 把分散的 Agent 遥测组装成一个持久化的统一会话结构：把 session 作为来源溯源保留、把父/子 Agent 的执行线分开、测量模型消息连续性，并把同一个已提交快照投影到存储、导出和本地预览。

核心价值：为「AI Agent 究竟做了什么、为什么这么做」提供一个可审计、可证据化的观测底座。

适合人群：

• 构建 / 运维 AI Agent 应用的平台与基础设施团队
• 需要审计 Agent 行为、做成本归因与质量度量的工程团队
• 研究 Agent 可观测性、会话模型与遥测组装的技术人员

使用前提：Go 工具链（自建）或预编译二进制 + Docker；当前阶段为 pre-alpha，会话模型与 Claude Code 数据映射已定义，收集与组装已实现，静态导出与 OTLP 推送尚未开始。

准备工作

1. 获取二进制：每个 release 都带 macOS / Linux / Windows 二进制包，或自行 make build 生成 ./bin/asz
2. 环境：Go（自建时）或 Docker（容器方式）
3. 数据源：目前唯一实现的适配器是 Claude Code（本地文件，无需配置，对已存在的历史也生效）；Codex、LangChain/LangGraph 为规划中
4. 配置：命令默认读取工作目录下的 asz.yaml，仓库根目录的那份是写全了所有值的默认配置
5. 成本：Apache-2.0 开源免费，本地运行无额外成本

快速上手（3 步）

第一步：构建（或用预编译二进制）

make build                 # 生成 ./bin/asz

也可以直接用 Docker 容器：docker run --rm -p 8787:8787 -v "$PWD/data:/asz/data" ghcr.io/apache/skywalking-ai-sessionizer:latest

第二步：发现并收集会话

./bin/asz sources          # 列出已发现的 session 及其来源
./bin/asz collect -once    # 落地当前磁盘上的一切

第三步：查看组装结果

./bin/asz view             # 在 http://127.0.0.1:8787 提供会话查看页

成功判定：view 启动后，列表页展示已组装的会话，并显示数据上次刷新与下次刷新时间。

初级用法

列出会话来源

./bin/asz sources 列出本机发现的 session 及其来源，是理解数据从哪来的第一步。

单次收集

./bin/asz collect -once 把当前磁盘上的所有遥测一次性落地为统一会话结构。

本地预览

./bin/asz view 提供本地页面；配合 Claude Code 适配器时，它会在同一进程内运行 collector 和 parser（-once 或按收集间隔），页面显示刷新时间。

高级玩法

统一会话模型

模型分五层：Conversation（持久身份与所有权边界）→ Segment（活动窗口，COMMIT 单元）→ Session（来源溯源）→ ExecutionStream（主 / 子 Agent 执行线）→ Context epoch → Talk（一次输入→运行→输出）→ Run → Step。身份由外部提供，绝不从人、账号或时间戳邻近性推断。

证据纪律

每条声明都带资格标记（observed_replayable / observed_report_only / proposed / unavailable），每条关联都带解析状态（exact_unique / exact_ambiguous / strong_inference / unresolved / conflict）。标识符有多个候选时保持模糊，绝不静默择一。

存储根复制

把存储根从别的机器复制过来时没有本地 source，view 直接提供已存在的内容。

小技巧

1. 先跑 ./bin/asz sources 确认能发现数据，再跑 collect
2. 读仓库根目录的 asz.yaml 了解每个配置项，无需读 Go 源码即可改配置
3. 关注 docs/ 下按 menu.yml 索引的官方文档与适配器说明
4. 项目处于 pre-alpha，功能边界以 README 的 Status 列表为准
5. 贡献时聚焦 schema、隐私安全 fixture、确定性组装与 golden tests

常见踩坑

踩坑 1：make build 失败

• 现象：构建报错
• 原因：缺少 Go 工具链或版本不匹配
• 解决：安装匹配版本的 Go，或改用 release 预编译二进制 / Docker 容器

踩坑 2：asz sources 看不到任何会话

• 现象：列表为空
• 原因：没有已实现的适配器对应的数据源（当前仅 Claude Code 本地文件）
• 解决：确认本机存在 Claude Code 的历史数据；Codex/LangChain 适配器尚未实现

踩坑 3：改了配置不生效

• 现象：asz 仍按旧配置运行
• 原因：命令只在没有 -config 时读工作目录的 asz.yaml
• 解决：确认在含 asz.yaml 的目录运行，或用 -config 显式指定路径

踩坑 4：静态导出 / OTLP 推送不可用

• 现象：找不到导出或推送功能
• 原因：README 明确标注「static export 与 OTLP push 尚未开始」
• 解决：这是 pre-alpha 的已知边界，不要假设功能已上线

踩坑 5：端口 8787 冲突

• 现象：view 报端口占用
• 原因：本地 8787 已被占用（注意与 niubigeo 等工具默认端口相同）
• 解决：换端口或先停掉占用进程

常见问题 FAQ

Q: 它解决什么问题？

A: 把 AI Agent 运行时的分散遥测（transcript/trace/日志/工具事件/子 Agent 元数据）组装为可持久化、可度量的统一会话结构，回答「整个对话做了什么、为什么这么做」。

Q: 成熟度如何？

A: pre-alpha。会话模型与 Claude Code 数据映射已定义并有证据支撑，收集与组装已实现，本地预览进行中，静态导出与 OTLP 推送未开始。

Q: 支持哪些 Agent 运行时？

A: Claude Code 已实现（本地文件、免配置）；Codex、LangChain/LangGraph 为规划中。

Q: 免费吗？

A: Apache-2.0 开源免费，Apache 官方子项目。

Q: 和 Langfuse / LangSmith 的区别？

A: Langfuse/LangSmith 侧重 LLM 应用的 tracing 与评测；SkyWalking AI Sessionizer 聚焦「跨进程、长生命周期的对话级」会话组装与证据溯源，以统一会话模型为第一公民。

进阶学习建议

掌握基础后，建议深入：

1. 读 Unified Conversation Model，理解 Conversation / Segment / Session / ExecutionStream 的边界设计
2. 对比 Langfuse、OpenTelemetry GenAI 语义约定，理解「trace 级」与「会话级」可观测性的分工
3. 跟踪 Codex、LangChain/LangGraph 适配器进展，评估在多运行时环境中统一观测的落地路径

参考链接

• 官方仓库
• 官方文档站
• Claude Code 适配器说明

最后更新：2026-09-04 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成