ratel-observability-assessment

/ratel-observability-assessment — 为 Agent 代码库启用原生 OTLP 遥测

像 Ratel 团队一样，为客户的代码库接入可观测性：检测技术栈，梳理 Agent 的心智模型，确定一套一致的命名和标记词汇，确定哪些仪表板能证明价值，启用 Ratel 的原生 OTLP 遥测，并选择团队已经导出数据到的 OTel 后端，然后撰写一份客户可据此采取行动的提案。提案就是交付物。不要编辑 Agent 代码，也不要调用任何后端 API。

Ratel 的遥测就是 OpenTelemetry：SDK 会原生发出 gen_ai.* span（semconv v1.42.0）形式的检索与工具漏斗数据，以及 ratel.* 扩展数据，并以标准 OTLP 格式导出。因此，接入方式不受厂商限制——只需启用原生遥测一次，然后将这些 span 导出到团队已经在使用的任意 OTel 后端（Langfuse、LangSmith、自有收集器或 Ratel Cloud — 即将推出）。此技能负责完整的决策：追踪应放在哪里、在 Ratel 的漏斗数据旁应添加哪些 Agent 级 span、应导出到哪个后端，以及哪些仪表板能证明价值。它是可观测性漏斗的入口，通常在 /ratel-assessment 将可观测性维度评为“薄弱”或“缺失”时进入。

最终确定的词汇和仪表板集会成为团队在其选择的后端中据以构建的约定，因此此处定义的 span/属性名称会实际显示在仪表板上。

理念：追踪心智模型，而非调用图

一种常见的失败模式是“给每个函数都包上一层 span”。这样会产生与代码调用图相符的数据，却无法告诉你 Agent 试图做什么。提案必须围绕一次轮次的概念结构——工作单元、步骤、会话——而不是源文件布局来构建可观测性。阅读 references/instrumentation-philosophy.md，了解完整指导以及需要在发现时指出的两种反模式（没有会话边界；工具调用被记录为无类型事件）。

工作流

第 1 步 — 检测技术栈

阅读清单文件，识别语言和框架。Ratel 的原生遥测支持 TypeScript 和 Python，因此技术栈概况主要用于确定使用哪个 SDK（@ratel-ai/sdk 或 ratel-ai），以及接入时使用哪些框架钩子。

# TypeScript / Node detection
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u

# Python detection
test -f pyproject.toml && grep -A 200 '^\[' pyproject.toml || true
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

根据依赖项将项目映射到以下某个技术栈类型：

清单中的信号	技术栈
ai、@ai-sdk/*	Vercel AI SDK
@mastra/core、直接调用 openai / @anthropic-ai/sdk 的手写循环	通用 TypeScript
openai / anthropic / langchain / llama_index（无 Agent 框架）	通用 Python
langgraph、crewai、agno、autogen	Agent 化 Python

如果信号重叠（例如，同时存在 LangGraph 监督器和内部直接调用的原始 OpenAI 请求），请将 Agent 化类型作为主要类型，并在提案中注明混合技术栈的情况。references/native-telemetry-setup.md 提供了适用于最终选定类型的具体接入方法（TypeScript + Python）。

如果完全无法识别任何 Agent 入口（没有 LLM 客户端导入、没有 Agent 框架、没有模型调用），请使用坦诚跳过路径。

步骤 2 — 梳理 Agent 的拓扑结构

启动一个 Explore Agent（如果代码仓库很小，也可以直接梳理），并引用文件路径回答以下四个问题：

1. 一轮对话从哪里开始？ — 入口点：HTTP 处理程序、CLI 动词、队列消费者、聊天平台 webhook。这是 session_id 所在的位置。
2. 工作单元有哪些？ — supervisor 函数、子 Agent 工厂、按角色专门化的循环。任何接收用户消息并返回响应的部分都算。这些将成为顶层边界。
3. 工具在哪里定义和调用？ — 工具注册表（tools: [...]）、@tool 装饰器、MCP 服务接线。每次工具调用都必须体现为一个带类型的工具调用步骤。
4. 子 Agent 在哪里将工作交接给其他子 Agent？ — supervisor → worker、并行分发、图节点转换。这些位置必须保留会话、用户和标签上下文。

在提案中用一张简短的拓扑图（ASCII 或 Mermaid）呈现这些信息。图不必面面俱到，但应让客户在实施时能一目了然。

步骤 3 — 检测导出的 OTel 后端

由于 Ratel 会发出标准 OTLP，唯一需要确认的后端问题是：这些 span 会发送到哪里？阅读 references/vendor-detection.md，并扫描清单依赖项、环境变量和初始化／导入位置，检查团队可能已在使用的各类后端（Langfuse、LangSmith、PostHog、Arize Phoenix、Helicone、OpenLLMetry/OTel GenAI、Braintrust）——它们都能接收 OTLP。如果已有 ratel-assessment 收集的可观测性信号，请加以复用。按照该参考文档的规则，记录检测到的后端及置信度（high / medium / low）——清单依赖项或初始化位置是强信号；单独的环境变量则是弱信号。

步骤 4 — 如果没有找到后端，给出建议

如果步骤 3 未发现任何信号（或只发现较弱、含糊的信号），不要猜测。使用 AskUserQuestion 询问团队运行的是哪个兼容 OTel 的后端，并提供以下选项：Langfuse、LangSmith、自有 OTel collector、其他、暂时没有。

• 如果他们说出一个后端，就以此为导出目标继续操作（置信度：用户明确说明）。
• 如果他们选择 其他，记录其名称；任何 OTLP 后端都可用——将其记录为导出目标。
• 如果他们选择 暂时没有，建议采用一个后端（Langfuse 和 LangSmith 是最快上手的原生 OTLP 选项；可自托管的 collector 也可行），并注明 Ratel Cloud（即将推出）是未来的官方选项。无论如何，都要提交完整提案。

步骤 5 — 启用原生遥测并规划 Agent 级跨度

Ratel 原生以 OTel 跨度形式发出其检索 + 工具漏斗。提案的插桩部分分为两部分：

1. 启用 Ratel 的原生 OTLP 遥测 — 链接 references/native-telemetry-setup.md。选择配置路径：全新项目使用 configureTelemetry() / configure_telemetry()（由 Ratel 管理 OTel 提供程序并导出到 RATEL_URL），或者将 ratelSpanProcessor() / ratel_span_processor() 接入团队现有的提供程序进行双路导出。说明哪种路径适合该代码库，以及原因。这是接线工作——下游技能无需再“渲染”任何内容。
2. 添加 Ratel 不会发出的 Agent 级跨度 — 对步骤 2 中的拓扑应用 references/instrumentation-philosophy.md（思维模型，而非调用图；两个反模式）和 references/semantic-conventions.md（工作单元命名、步骤类型、会话 / 线程来源、标签、属性键）。Ratel 的 ratel.* 漏斗跨度会与客户自己的 LLM 调用和 Agent 跨度加入同一条跟踪链 — Ratel 不会发出 chat <model> 跨度，因此要命名会话边界、Agent 步骤和模型调用跨度，以及会话 ID 来源。说明要采集什么以及为什么。

将提案引入的每个跨度 / 标签 / 属性键都列在一张表中，方便客户粘贴到共享文档中，以便下方的仪表板按名称分组。

步骤 6 — 规划仪表板

根据 references/general-agent-dashboards.md，选择插桩能够支持的 Agent 健康状况仪表板：延迟与成本概览、错误概况、工具使用情况、会话质量、模型与提示词漂移。无论是否使用 Ratel，这些仪表板都很有用。使用团队在步骤 3 中选择的 OTel 后端进行呈现。

仅在清单中包含 Ratel 或客户已同意采用 Ratel 时，才有条件地添加 Ratel 价值组。根据 references/ratel-value-map.md 命名这些仪表板（Token 成本与节省、检索质量、来源拆分、技能检索健康状况、上游健康状况），并为任何取决于路线图的项目添加脚注。如果清单中没有 Ratel，且没有引入计划，则完全跳过此组——不要预先在客户拥有的文档中植入 Ratel 推广内容。

列出哪些仪表板以及每个仪表板的重要性（每个仪表板用一句通俗易懂的话说明）。每个仪表板用于分组的具体跨度 / 属性名称见 references/semantic-conventions.md 和 references/ratel-value-map.md；客户在其后端的界面中构建组件。

Step 7 — 编写方案

写入 <repo>/.ratel/ratel-observability-assessment.md——这是一个持续更新的单一文件，不带日期戳。如果 .ratel/ 目录不存在，请创建；如果仓库已经采用其他文档规范，请先询问用户确认路径。重新运行时覆盖原文件。

方案必须按以下顺序包含：

1. 摘要——用一段话说明：检测到的技术栈、Agent 拓扑、已有的埋点（如有），以及本方案新增的内容。
2. 导出目标——OTel 后端和可信度等级（或用户在 Step 4 中给出的答案）。
3. 拓扑——Step 2 中的图示。
4. 埋点策略——如何启用 Ratel 的原生遥测（采用 Step 5 中的哪种设置路径），以及 Agent 级别的 span/tag/attribute 表格和会话边界方案；指出发现的任一种反模式。
5. 建议的仪表板——Agent 健康度组，以及有条件时的 Ratel 价值组，来自 Step 6，并分别附上一句「原因」。
6. Ratel 角度（有条件，仅当存在或计划使用 Ratel 时）——根据 references/ratel-value-map.md，说明哪些发现对应哪些 Ratel 功能。
7. 建议的下一步——根据下方路由表，提供相关的独立后续步骤。

在聊天中内联打印目录——最多七个项目——导出目标和建议的下一步。不要在聊天中粘贴完整方案正文；文件才是交付成果。

Step 8 — 提供独立的后续步骤

在方案和内联摘要末尾添加以下路由：

情况	路由至
启用遥测	references/native-telemetry-setup.md — 具体的 TS + Python 接线方式（全新项目使用 configureTelemetry / 双路导出使用 ratelSpanProcessor）、内容捕获的选择加入，以及本地 trace 流
通过 Ratel 加载 Agent 的工具和技能	/ratel-integrate — 实现 SDK 或框架适配器接线，并验证每个 Agent 的能力边界；可观测性不是前置条件

诚实跳过路径

如果在 Step 1 之后，仍然找不到任何 LLM 客户端导入、Agent 循环或模型调用，请停止。不要编写方案。告知用户：

未检测到 Agent 接口——仅检查了 <files looked at>。如果此代码库中的 Agent 代码位于非标准位置，请告诉我具体位置，我会重新运行。

在非 Agent 代码库中强行编写可观测性方案，会产生无人使用的文档并损害合作信任。最好跳过并询问。

Ratel 的原生遥测支持 TypeScript 和 Python。如果 Agent 使用其他语言（例如 Ruby、Go 或小众框架），仍然要生成方案——埋点策略和仪表板集与技术栈无关，团队可以通过 TS/Python Ratel Local sidecar 导出 Ratel 的 OTLP spans——但要将进程内 SDK 接线标记为「仅支持 TS/Python」，并询问 Ratel Local (MCP) 是否适合该技术栈的集成模式。不要假装有把握。

参考文件

• references/instrumentation-philosophy.md —“追踪思维模型，而非调用图”以及两种反模式
• references/native-telemetry-setup.md —如何启用 Ratel 原生 OTLP 遥测（TS + Python）：span 词汇、从零开始与双重导出、内容捕获的选择加入、本地追踪流
• references/semantic-conventions.md —漏斗与你的 Agent span 共用的 OTel span/属性词汇
• references/general-agent-dashboards.md —与技术栈无关的 Agent 健康仪表板目录
• references/ratel-value-map.md —Ratel 提供的功能 → 可观测信号的唯一事实来源；请通读整个套件
• references/vendor-detection.md —各后端的检测信号，以及如何将 Ratel 的 OTLP span 导出到各个后端
• references/finding-catalog.md —在后端查看追踪记录时可查找的 Agent 故障模式目录