TraceRoot
让 AI Agent 从线上故障定位到验证修复的可观测性平台。
- Star 数
- ★ 1.3k
- 最近更新
- 今天
- License
- NOASSERTION
- 主语言
- TypeScript
- FA 评分
- 42/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code · OpenAI API · Claude API
- 费用
- 有免费版，另有付费云服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 维护线上客服 Agent 的工程团队，可用 Detectors 监测生产 trace 中的幻觉或意图漂移，再将确认案例沉淀为回归评测集。
- 不适合
- 需要完全离线或数据不出本地的团队，调试层会读取生产源码与 GitHub 历史
- 不愿把生产源码和 GitHub 仓库接入沙箱的团队
- 需要稳定生产级自托管部署的团队，K8s/Helm/Terraform 路线仍属实验阶段
这个 Agent 能做什么，适合哪些场景？
TraceRoot 是面向 AI Agent 的开源可观测性与持续改进平台，覆盖追踪、线上检测、根因分析和离线评测。它通过兼容 OpenTelemetry 的 SDK 捕获 LLM 调用、Agent 动作与工具使用，并用 Detectors 筛选需要关注的线上 trace。被确认的问题可转成 golden dataset，再通过 TraceRoot CLI 或 SDK 运行离线 eval 验证修复。其 Agentic Debugging 层连接含生产源码的 sandbox，并关联 GitHub 的提交、PR 和 issue，以定位失败代码行并可创建修复 PR。团队可使用 TraceRoot Cloud，也可通过 Docker 本地运行；AWS 的 Kubernetes、Helm 与 Terraform 部署仍标为实验性。
应用侧可调用 Python 的 traceroot.initialize(integrations=[Integration.OPENAI])，以 @observe(name="my_agent", type="agent") 包装函数；或在 TypeScript 中调用 TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } })，以 observe({ name: "my_agent", type: "agent" }, ...) 包装异步 Agent，并在结束时执行 TraceRoot.shutdown()。SDK 记录 LLM 调用、Agent 动作和工具使用的 trace。Detectors 使用 LLM-as-judge 评估进入的 trace，检查幻觉、工具或逻辑失败、安全违规和意图漂移，并可发出邮件和 Slack 告警、触发根因分析。调试层在包含生产源码的 sandbox 中分析问题，关联 GitHub 提交、PR 与未关闭 issue，定位失败行，并按项目说明创建已验证的修复 PR。确认的线上发现可一键成为 golden dataset；离线 eval 可从 TraceRoot CLI 或 SDK 在 Claude Code、Codex、Cursor 等编码 Agent 内运行，用于检验修复。
- 维护线上客服 Agent 的工程团队，可用 Detectors 监测生产 trace 中的幻觉或意图漂移，再将确认案例沉淀为回归评测集。
- 使用 OpenAI Chat Completions 或 Responses API 的 Python 或 TypeScript 团队，可通过对应 SDK 初始化和 observe 包装采集调用与 Agent 运行。
- 需要排查工具调用不稳定或逻辑错误的团队，可让 Agentic Debugging 在生产源码 sandbox 中关联 GitHub 历史来定位失败代码行。
- 使用 LangChain、LangGraph、CrewAI、AutoGen 或 OpenAI Agents SDK 的开发者，可接入项目列出的框架追踪集成。
- 准备在每次代码改动后验证 Agent 修复的团队，可将线上发现转为 golden dataset，并在 Codex、Claude Code 或 Cursor 中运行离线 eval。
如何安装或部署这个 Agent？
Python：执行 pip install traceroot openai。TypeScript：执行 npm install @traceroot-ai/traceroot openai。本地开发可执行 git clone https://github.com/traceroot-ai/traceroot.git、cd traceroot、make dev；完整本地 Docker 运行可执行 make prod。README 未给出 TraceRoot Cloud 的认证变量、SDK 上报端点或模型提供商密钥的具体配置方式；示例会创建 OpenAI 客户端，因此实际模型调用需要该客户端可用的认证配置。
如何使用这个 Agent？
Python 的最小调用是导入 traceroot、Integration、observe 和 OpenAI，执行 traceroot.initialize(integrations=[Integration.OPENAI])，再用 @observe(name="my_agent", type="agent") 标注调用 client.chat.completions.create(...) 的函数。TypeScript 中先执行 TraceRoot.initialize({ instrumentModules: { openAI: OpenAI } })，用 observe({ name: "my_agent", type: "agent" }, async (...) => ...) 包装函数，并在 finally 中执行 await TraceRoot.shutdown()。若自行部署平台，可在仓库根目录使用 make dev 或 make prod；生产 AWS 路径位于 deploy/，项目说明其 Kubernetes、Helm、Terraform 方案仍属实验性。
这个 Agent 有哪些优点和局限？
- 把线上 LLM-as-judge 检测、根因分析、golden dataset 和离线 eval 串成同一改进闭环，而不止提供 trace 浏览。
- 调试流程明确利用生产源码 sandbox 和 GitHub 的提交、PR、issue 来定位失败行，并说明可创建修复 PR。
- 同时提供 Python 与 TypeScript SDK，并列出 OpenAI、Anthropic、Gemini、Mistral、OpenRouter 等提供商及多种 Agent 框架的追踪路径。
- 可选择 TraceRoot Cloud、Docker 本地运行或 AWS 的 Kubernetes/Helm/Terraform 部署，且说明支持自带模型提供商密钥。
- README 没有提供 Cloud、SDK 上报或 GitHub 访问所需令牌、环境变量、权限范围与认证配置的具体步骤。
- 根因分析需要连接包含生产源码的 sandbox，并读取 GitHub 历史；这会带来源码访问、隔离和权限审查成本。
- AWS 的 Kubernetes、Helm 与 Terraform 生产部署被明确标为实验性，生产采用前需要额外验证。
- Detector 依赖 LLM-as-judge；README 未说明评审模型、阈值、误报控制、数据保留或告警配置细节。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| TraceRoot 当前 | 42 · 缺口较多 | 云服务 / SaaS免费版 + 付费版 | ★ 1.3k | 今天 | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| DataBuff | 41 · 缺口较多 | 自托管服务免费 + 模型费 | ★ 722 | 1 个月前 | Java | OpenAI API |
| Laminar | 41 · 缺口较多 | 自托管服务免费版 + 付费版 | ★ 3.5k | 今天 | TypeScript | OpenAI API · Claude API |
| HolmesGPT SRE Agent | 57 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 3.8k | 2 天前 | Python | OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：README 提到 BYOK 和自托管，但未明确权限最小化；无用户确认机制；数据流透明度有限，仅提及 OpenTelemetry 收集；敏感数据处理有 SECURITY.md 但细节不足；依赖有版本上限但未全面审计；外部影响包括发送通知和创建 PR，但未说明授权；无回滚机制；来源归属有贡献者列表但未验证。扣分原因：缺乏具体实现细节。
证据显示：测试覆盖了 detector 条件和 trace 命名，但未覆盖整个系统；依赖声明存在但未验证可用性；失败消息在测试中有部分体现，但整体不足。扣分原因：静态审查无法验证运行时行为。
证据显示：README 描述了多种场景和集成，但能力边界不明确；触发条件有测试但未完整文档化；环境适配有 Docker 和 Terraform 但 experimental。扣分原因：缺少详细配置说明。
证据显示：信息架构清晰，有 README、SECURITY、CONTRIBUTING；安装说明存在但不够详细；命名稳定但版本号未明确；有示例但无 FAQ；已知限制未明确；许可证为 Apache 2.0 但含企业版；版本变更日志缺失；维护责任有贡献者但未明确。扣分原因：缺少 changelog 和详细限制。
证据显示：输出可用性有示例代码；边际价值高，解决实际问题；成本效益未量化。扣分原因：无成本数据。
证据显示：README 中的声明部分有文档支持，但未完全可追溯；跨来源验证有限；事实与推断未明确区分。扣分原因：静态审查无法验证。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 静态审查无法验证运行时行为，所有评分基于源代码和文档。
- 依赖安全未全面审计，建议检查依赖漏洞。
- 企业版功能可能影响许可证合规。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v1.3.6 v1.3.6 - Security fixes: model provider keys, better-auth
发布说明摘录
Security - Reject blank model provider API keys. A bring-your-own-key model provider saved with a whitespace-only key is now rejected when created or updated, and a stored blank key is treated as no key when a provider is resolved. This closes a path by which a workspace admin could make the server use its own environment provider key. Details in the [security advisory](https://github.com/traceroot-ai/traceroot/security/advisories/GHSA-r4ph-92m3-xw89). - Upgrade better-auth to 1.7.15 for security advisories. …在 GitHub 查看 ↗ -
v1.3.5 v1.3.5 - Async redact in TypeScript
发布说明摘录
This release documents async redact in the TypeScript SDK. From @traceroot-ai/traceroot 0.8.0, redact runs at export rather than during the request, may return a promise, and so can call a detection service to remove names and addresses that a pattern match misses. Improvements - Async redact in TypeScript. The Data Capture and Privacy page now covers how TypeScript redact differs from Python: it runs at export, may be async, and each batch gets 5 seconds. A promise that rejects or does not settle in time fails closed the same way a throw does, storing [redaction failed]. …在 GitHub 查看 ↗ -
v1.3.4 v1.3.4 - Tool call cost, improved detector judge
发布说明摘录
This release counts the reported cost of tool and API calls, so a paid search, scrape or data API call reaches the trace total and shows on its span. The detector judge reads a compact text view of the trace instead of raw span JSONL, which removes most of the false positives caused by cut-off input. The rest is follow-through on last release's onboarding: the manual steps now say how the key reaches the app and name TRACEROOT_HOST_URL for self-hosted deployments, the device page is worded for setup as well as login, and the SQL gateway describes a result's columns even when it has no rows. …在 GitHub 查看 ↗
常见问题
它只做 trace 收集吗？
是否只能使用某一家模型供应商？
Agentic Debugging 会访问哪些工程资源？
能否自托管？
make dev，本地 Docker 模式使用 make prod；AWS Kubernetes、Helm、Terraform 路径存在，但仍属实验性。