用途
Agent Observability Trace RCA 是一个面向生产环境 LLM 应用的根因分析技能。它通过搜索生产追踪（trace）并沿 span 树从症状走到根因，回答“LLM 应用为什么失败”这类问题。技能会根据可用信号自动选择最佳分析模式，并在首次面向用户的输出中声明所选模式（而非询问），同时给出一行覆盖提示。
主要能力
技能支持三种分析模式：
- 评估信号（Eval Signal）：基于 LLM 裁判的结论与推理（通过/失败率、评分）。当应用配置了评估器时自动选用。
- 错误信号（Error Signal）：基于运行时错误（@status:error、错误类型、堆栈跟踪）。当未配置评估器，或用户明确询问错误/崩溃时选用。
- 通用（Generic）：基于结构性异常（延迟、agent 循环、检索未命中）。当显式指定 mode=generic，或第一阶段未发现强信号时选用。
方法论流程为：解析 → 搜索 → 观察 → 开放编码 → 轴向编码 → 根因导航 → 建议。
使用方式
典型用法示例：
- 询问“<ml_app> 在过去 <timeframe> 出了什么问题”
- 询问“<ml_app> 今天为什么失败”
- 分析“<ml_app> 上 <eval_name> 的评估失败”
- 查看“<ml_app> 在过去 <timeframe> 的错误”
- 对“<eval_name> 的低分进行根因分析”
输入参数：
ml_app：必填（或提供 eval_name），要分析的应用。eval_name：可选，一个或多个要关注的评估器，隐含评估信号模式，可传列表进行多评估分析。timeframe：可选，默认 now-24h，回溯时间范围。mode：可选，默认推断，可显式覆盖为 eval、errors、generic，跳过推断。failure_filter：可选，缩小范围，如 "errors"（路由到错误信号路径）、"high latency"（获取后按持续时间排序）、"low scores on <eval>"（提升为 eval_name）、工具名或 span 名（@name:<x> 查询）。
若既未提供 ml_app 也未提供 eval_name，技能会向用户询问。
后端检测
每次调用开始时，在采取任何行动前先确定使用哪个后端：
- 若用户在任何位置传入
--backend pup，立即使用 pup 模式，跳过步骤 2–4。 - 检查活动工具列表中是否存在 MCP 工具，规范信号是
mcp__datadog-llmo-mcp__list_llmobs_evals是否可用。 - 若存在 MCP 工具，全程使用 MCP 模式。
- 若不存在 MCP 工具，检查 pup 是否可执行：通过 Bash 运行
pup --version，返回含 "version" 的 JSON 即确认可用。 - 若 pup 响应，全程使用 pup 模式，将每个 MCP 工具调用翻译为对应的 pup 等价命令。
- 若两者都不可用，停止并告知用户：
"Neither the Datadog MCP server nor the pup CLI is available. Connect the MCP server (claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=llmobs') or install pup."
pup 调用规则：通过 Bash 调用 pup llm-obs <subcommand> [flags]；pup 始终输出 JSON，直接解析；若返回认证错误，提示用户运行 pup auth login 并停止；可在单条消息中并行发起多个 Bash 调用；时间标志接受裸时长字符串（1h、7d、30m）和 RFC3339 时间戳，不要使用 now- 前缀字符串（如 now-7d → 7d）。
可用工具
评估发现与概览：
list_llmobs_evals：发现某 ml_app 的所有已配置评估，用于第 0 阶段模式推断。get_llmobs_eval_aggregate_stats：某评估在时间窗口内的通过/失败率或分数分布。get_llmobs_evaluator：完整评估器配置（提示模板、评估标准、span 过滤器、采样、提供方），替代已弃用的 get_llmobs_eval_config。
追踪与 span 探索：
search_llmobs_spans：按标签、span 类型、状态、查询语法查找 span，用游标分页，是第 1 阶段入口。get_llmobs_span_details：元数据、评估（分数、标签、推理）、状态、错误字段、持续时间，以及显示可用字段与大小的 content_info 映射。get_llmobs_span_content：获取 span 字段的实际内容，支持通过 path 参数进行 JSONPath 定向提取。get_llmobs_trace：完整追踪层级，以 span 树呈现，含按类型统计的 span 数量。find_llmobs_error_spans：追踪中的所有错误 span，含错误类型、消息、堆栈和传播上下文。expand_llmobs_spans：加载折叠追踪节点的子节点。get_llmobs_agent_loop：按时间顺序的 agent 执行时间线（LLM 调用、工具调用、决策），可能返回空。
适用场景
适用于生产环境 LLM 应用的故障诊断，包括：评估失败排查、运行时错误与崩溃分析、延迟与 agent 循环等结构性异常定位、RAG 检索未命中分析，以及多评估器交叉校准检查。
限制
- 需要 Datadog MCP 服务器或 pup CLI 之一可用，否则无法运行。
- 评估名称并非全局唯一，若只提供 eval_name 而未提供 ml_app，span 搜索会返回所有共享该评估名称的应用结果。
- 部分评估为 JSON 类型，分数不索引在
@evaluations.custom.<eval_name>:*字段上，需回退到按 span 名称或类型搜索并检查输出载荷。 - MCP 工具 span 有时报告 @status:ok 但输出载荷中携带 "isError": true，这类软错误无法通过 @status:error 查询发现。
get_llmobs_agent_loop可能返回空，需使用回退方案。- 若评估配置为 OOTB（内置），提示不可检查。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。