从生产 LLM 追踪数据自动生成评测器套件（在线草稿/离线代…

当需要基于生产 LLM 追踪样本为某个 ml_app 生成评测器（在线 LLM-judge、离线 SDK 代码、框架无关 JSON 规范或实验数据集）时使用。

适用场景

解决思路

1. 后端检测：每次调用开始时先确定使用 MCP 还是 pup。若参数含 --backend pup 则直接用 pup 模式；否则检查工具列表中是否存在 mcp__datadog-llmo-mcp__list_llmobs_evals，存在则用 MCP 模式；不存在则运行 `pup --version`（返回含 "version" 的 JSON 即可用）进入 pup 模式；两者都不可用则停止并提示用户连接 MCP 服务器（`claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=llmobs'`）或安装 pup。
2. pup 调用规则：通过 Bash 执行 `pup llm-obs <subcommand> [flags]`；pup 始终输出 JSON 可直接解析（无需像 MCP 那样解包 content block）；认证错误时提示用户运行 `pup auth login` 并停止；并行化时在单条消息中发起多个 Bash 调用；时间参数用裸时长字符串（1h、7d、30m）或 RFC3339，不要用 now- 前缀（now-7d → 7d）；批量搜索阶段用 --summary 剥离 payload 只保留元数据。
3. 每次调用开始时生成一个 8 位十六进制 invocation ID（如 3a9f1c2b）并在整个调用中保持不变；每次 MCP 工具调用的 telemetry.intent 前缀为 `skill:agent-observability-eval-bootstrap[<inv_id>] — <原因>`，仅首次调用用 `skill:agent-observability-eval-bootstrap:start[<inv_id>] — `。
4. Phase 0 解析输入与入口模式：提取 ml_app（第一个非 flag 参数）、--timeframe（默认 now-7d）、--trace-limit（默认 20，上限 50）、--sdk-code、--data-only、--emit-dataset <path>；三个模式 flag 最多只能有一个，多于一个则报错；--emit-dataset 设 output_mode=emit_dataset 并直接跳到 Phase 3D；--sdk-code → sdk_code；--data-only → data_only；否则默认 publish。ml_app 缺失则询问用户。
5. 自动检测入口模式：对话中含 RCA 报告（查找 "Failure Taxonomy" 标题、结构化失败模式或严重性评级）或用户提供自由文本失败假设 → from_rca 并提取分类；否则 cold_start。
6. 映射现有评测覆盖（data_only 模式跳过）：调用 list_llmobs_evals（组织级，客户端按 ml_app 过滤），对每个 source=custom 的评测调用 get_llmobs_evaluator 检查其 prompt 模板、目标、采样和过滤，推断覆盖的质量维度；所有调用在单条消息中并行；跳过 source=ootb。publish 模式还要记录现有自定义评测的模板变量约定。
7. 检测 notebook 上下文：扫描对话中由 /eval-trace-rca 产生的 Datadog notebook URL（模式 https://app.datadoghq.com/notebook/{numeric-id}），存为 rca_notebook_url 并提取数字 ID 作为 rca_notebook_id。
8. Phase 1 冷启动路径：调用 search_llmobs_spans(query="@ml_app:\"<ml_app>\" @status:ok", root_spans_only=true, limit=50, from=<timeframe>) 采样（过滤 @status:ok 因错误 span 无输出可评）；同一消息中调用 search_llmobs_spans(query="@ml_app:\"<ml_app>\" session_id:*", limit=20, from=<timeframe>) 做会话探测——≥1 结果则 sessions_present=true 并注意同一 session_id 是否跨多个 trace_id；0 结果则 sessions_present=false 且不提议任何 session 作用域评测器。
9. 按 trace_id 分组调用 get_llmobs_span_details，检查 content_info 分类应用画像：有 messages → LLM/chat；有 documents → RAG；含 agent kind → Agent；有 metadata → 有自定义元数据；一个 trace 中多种 span kind → 多步应用（至少一个 trace 作用域评测器）；同一 session_id 跨多个 trace_id → 多 trace 会话（至少一个 session 作用域评测器）。对 agent/多步应用再对 2-3 个 trace 调用 get_llmobs_trace 查看完整 span 层级。
10. 对每个候选质量维度按顺序问两个问题：(1) 判定是否依赖多个 span（如忠实度依赖 retrieval span 的文档和 llm span 的答案）？是则 publish 模式用 trace 作用域；(2) 仅当 (1) 为否时，选信号最丰富的单个 span（root 有摘要，LLM 子 span 有完整系统提示+工具调用结果+推理链）。记录 span-kind 直方图。
11. 调用 get_llmobs_span_content 提取代表性 span 内容，按应用画像取字段：LLM/chat 取 messages（path=$.messages[0] 取系统提示）和 output；RAG 取 documents、input、output；Agent 先 get_llmobs_agent_loop 再取 messages；有 metadata 取 metadata。所有调用在单条消息中并行。阅读时捕获两类信号：通用质量信号（成功长什么样、输出方差、安全信号）和领域信号（每 5-10 个 trace 记录：反复出现的意图/问题类别、输出中的实体如 URL/机构名/金额/日期/ID、工具参数形状、人设/语气规则、领域特定失败模式）。
12. Phase 1 RCA 路径：从 RCA 报告提取失败分类，每个 High/Medium 严重性的失败模式成为评测目标；同时运行会话探测设置 sessions_present。检查 Root Cause 列是否有 Instrumentation Deficiency、Harness Deficiency、Runtime Error、Upstream Data Issue 等基础设施根因，若有则暂停询问用户要行为靶向（推荐，衡量模型是否产生正确具体输出）还是产物靶向（作为回归守卫，检测特定损坏输出）还是两者都要。若全部为行为根因则跳过此步。对每个目标：RCA 含 trace ID 则直接用，否则搜索匹配 trace，每个目标取 2-3 个 trace 用 get_llmobs_span_content 理解具体模式。
13. Phase 2 提议评测器套件：按从广到细排序。1) 领域特定评测器（最高杠杆，从 Phase 1 领域信号派生）：反复出现的意图/问题类别 → intent_classification 或 intent_handling_correctness；应用产生的特定实体 → 每个实体正确性评测器（如 cited_url_is_real、agency_name_matches_request）；工具参数形状 → 每个非平凡 schema 工具的参数正确性评测器；人设/语气期望 → cites_a_source、refuses_medical_advice、tone_matches_brand；领域特定失败模式 → 每个反复失败模式一个评测器。用用户面向的关注点命名而非技术检查。2) 结果评测器（task_completion、answer_correctness、response_groundedness）。3) 格式评测器（valid_json_output、response_length、citation_format）。4) 安全评测器（no_pii_leakage、scope_adherence、no_hallucination）。
14. 提议数量指导：目标 8-15 个评测器，分布在四个类别（领域特定通常最大，结果第二，格式和安全较小）；简单单 LLM 调用应用可少些，agent/RAG 应用倾向上限；每个领域特定提议至少有一个采样 trace 中的观察模式支撑；把提议当作候选集让用户裁剪。
15. 去重（data_only 模式跳过）：覆盖以 (维度, 作用域) 为键而非仅维度。已启用的 span 作用域评测器（OOTB 或自定义）不阻止为同一维度提议 trace 或 session 作用域评测器；已启用的 trace 作用域自定义评测器阻止另一 trace 作用域同维度评测器；已禁用的 OOTB 评测器不提议新的自定义 span 作用域评测器，而是在提议中提示在 UI 中启用；提议开头给出覆盖摘要行；若所有维度在适当作用域都已覆盖则明确说明并询问用户要 (a) 审查/改进现有评测提示 (b) 增加额外维度覆盖 (c) 仍继续。
16. 每个提议评测器包含：Name（须匹配 ^[a-zA-Z0-9_-]+$）、Type（LLMJudge/内置/BaseEvaluator 子类；publish 模式仅支持 LLM-judge，代码类检查不能静默丢弃，须列在同一提议表中并标记在 "Not publishable in this mode" 小节）、What it measures（1-2 句）、Target span、Pass/fail criteria、Template variables、Evidence（至少一个 trace 链接）、publish 专属字段（integration_provider 默认 openai、model_name 默认 gpt-5.4-mini、sampling_percentage 默认 10、eval_scope 默认 span、filter）、integration_account_id（从同 ml_app 现有评测器自动检测，绝不向用户索要原始 UUID）。
17. publish 模式作用域分类（不问用户，按评测器分类让用户在检查点覆盖）：若 Phase 1 发现多步 trace（≥2 种 span kind 或 agent root 下有 tool/retrieval/workflow span），必须走查四个规范 trace 作用域用例并明确决定适用（含 eval_scope: trace）或不适用（在 "Skipped trace-scope candidates" 小节记录一行原因）：goal_completion（agent 是否完成用户请求）、tool_use_correctness（工具和参数是否正确）、rag_faithfulness（答案是否基于检索文档）、conversation_quality（多轮 LLM 调用间连贯性）。
18. 仅当 sessions_present 时走查四个规范 session 作用域用例并明确决定适用或不适用：session_goal_completion（整个会话中用户目标是否达成）、multi_turn_conversation_quality（跨轮连贯性、记忆、一致语气）、user_frustration_signals（会话中的挫败/困惑/重复/放弃）、agent_consistency_across_session（跨 trace 一致性和错误恢复）。sessions_present 为 false 则完全跳过 session 作用域并注明。
19. 其他评测器按顺序应用作用域测试：(1) 能否从单个 span 的 meta.input + meta.output 正确判定（考虑其他 span 不会改变判定）→ span；(2) 否则若可从单个 trace 的 span 回答 → trace（名称含 grounding/faithfulness/hallucination/completeness/correctness across steps/consistency/workflow 时默认 trace）；(3) 否则若需同一 session_id 中多个 trace 的上下文且 sessions_present → session（名称含 session/conversation/across turns/over time/satisfaction/frustration/abandonment 时默认 session），sessions_present 为 false 则回退 trace 并注明限制。
20. 权衡（不要让这些主导选择）：trace 作用域成本高于 span（每个完成 trace 一次判定、更大 prompt、3 分钟触发延迟）；session 作用域成本最高（每个完成会话一次判定、30 分钟不活动后完成、最大 payload 上限 10000 span）。这些是成本控制杠杆，用 sampling_percentage 和 filter 处理，不要降级作用域。
21. 在提议表中加 Scope 列和每个评测器一句理由；跳过的规范 trace/session 作用域用例列在对应 "Skipped …-scope candidates" 小节并给原因。
22. 强制检查点：必须输出提议并等待用户确认才能继续。输出格式含 App profile、Entry mode、提议表（#/Name/Type/Scope/Measures/Pass Criteria）、每个评测器的详情（Target span、Rationale、Scope 理由、Evidence 链接）、Skipped trace-scope candidates、Skipped session-scope candidates、Session scope skipped 说明、Not publishable in this mode 小节。询问用户保留/删除/重命名哪些，sdk_code 模式可加自定义评测器或改 provider/model，publish 模式可覆盖 integration_provider/model_name/sampling_percentage/eval_scope/root_spans_only/filter。用户确认前不得进入代码生成。
23. Phase 3 按 output_mode 分支：publish → Phase 3C；sdk_code → Phase 3A；data_only → Phase 3B；emit_dataset → Phase 3D。publish 运行后用户若要求离线代码或可移植规范，不要重跑 Phase 1-2，复用已确认套件直接跳到 Phase 3A/3B，把在线 prompt 模板转为离线 LLMJudge（用通用 {{input_data}}/{{output_data}} 占位符，保留 rubric 和通过标准），把无法在线发布的代码类检查生成为真实 BaseEvaluator/内置评测器。
24. Phase 3A 生成代码规则：1) prompt 必须基于生产 trace 中实际观察到的模式，绝不写通用 prompt；2) 模板变量保持通用（用 {{input_data}}/{{output_data}} 顶层占位符，不引用嵌套 span 路径），在每个评测器上方加注释说明设计用于什么数据及用户应如何适配；3) 用最窄的评测器类型（能用 JSONEvaluator/RegexMatchEvaluator/StringCheckEvaluator/LengthEvaluator 就不用 LLMJudge）；4) BaseEvaluator 子类在 __init__ 调 super().__init__(name=name)，evaluate() 返回 EvaluatorResult，不在 evaluate() 中修改实例属性（线程安全）；5) 名称匹配 ^[a-zA-Z0-9_-]+$ 用 snake_case；6) 导入集中在文件顶部只导入实际使用的；7) 所有评测器收集到文件底部的 evaluators 列表；8) 匿名化 PII。
25. Phase 3A 输出格式：文件头 docstring 含 ml_app、生成日期、应用画像、覆盖的质量维度及证据链接、用法示例；按类别分节（Outcome/Format/Safety，仅含有的类别）；底部 evaluators 列表。写到 ./evals/{ml_app}_evaluators.py（未指定时），显示摘要表和下一步。
26. Phase 3A notebook 导出：若 Phase 0 检测到 rca_notebook_url，询问追加到该 notebook 还是新建独立 notebook；追加用 mcp__datadog-mcp__edit_datadog_notebook（id=rca_notebook_id, append_only=true）；新建用 mcp__datadog-mcp__create_datadog_notebook（name="Eval Bootstrap: {ml_app} — YYYY-MM-DD"、type=report、单 markdown cell、time={"live_span": "1h"}）。notebook 创建回退模式：先试 MCP；认证/权限错误（401/403）停止并告知用户；字段验证错误修正该字段重试一次；其他错误回退 pup——把 payload 写到 /tmp/nb_bootstrap_{ml_app}.json 作为完整 API envelope {"data": {"attributes": {"name": ..., "time": ..., "cells": [...]}, "type": "notebooks"}}，运行 `pup notebooks create --file /tmp/nb_bootstrap_{ml_app}.json`；pup 也不可用则在聊天中渲染 markdown。成功后输出 URL。
27. Phase 3B 生成 JSON 规范：输出到 ./evals/{ml_app}_eval_spec.json，schema 含 schema_version、generated_at、generated_by、app（ml_app/app_type/trace_window/trace_count）、evaluators 数组（name/category/type/description/target_span/scoring/rubric/implementation_hints/evidence）、sample_records 数组（trace_id/span_id/input/output/suggested_labels）。type 为 llm_judge 或 code_check；rubric 用 {{input}}/{{output}} 通用占位符（非 {{input_data}}）；implementation_hints.notes 给框架无关指导（OpenAI Evals/Braintrust/Promptfoo）；sample_records 取 10-20 个代表性 trace，suggested_labels 是 Claude 的最佳猜测非 ground truth；匿名化 PII。用 Write 工具 2 空格缩进写入，显示摘要和下一步。
28. Phase 3C 发布前检查（单条消息并行）：对每个提议 eval_name 调用 get_llmobs_evaluator——未找到则安全创建；已找到则向用户展示 diff 并询问覆盖/重命名/跳过。覆盖时保留已取配置为基底合并生成字段后发送完整对象（MCP 工具是全量替换，省略的字段会重置为默认）；重命名则加后缀（如 _v2）当新评测器；跳过则从发布集移除。
29. Phase 3C 发布约定：必需参数 eval_name、application_name（=ml_app）、enabled、integration_provider、model_name、prompt_template、parsing_type、output_schema 及 telemetry.intent。默认：enabled=false（始终）、integration_provider=openai、model_name=gpt-5.4-mini、temperature=0、parsing_type=structured_output、sampling_percentage=10（span）/5（trace）/5（session）、eval_scope=span（按 Phase 2 规则自动提升为 trace 或 session）。prompt_template 转为 {role, content} 消息数组（system + user），用 span 数据占位符而非离线 {{input_data}}/{{output_data}}。
30. 在线模板变量：span 作用域占位符解析单个 span JSON，用内置别名 {{span_input}}/{{span_output}}（LLM span 映射到 meta.input/output.messages[*].content，其他 span 映射到 meta.input/output.value）或显式点路径（{{meta.input.value}}、{{meta.input.messages[*].content}}、{{meta.input.messages[0].content}}、{{meta.output.messages[*].content}}、{{meta.input.documents}}、{{meta.metadata.<key>}}、{{meta.tool_definitions}}、{{*}}）。trace 作用域解析 trace payload {spans: [...]}，用 {{spans[N]...}}、{{spans[*]...}}、{{spans[field.path:value]...}}（如 {{spans[meta.span.kind:tool]}}、{{spans[meta.span.kind:retrieval].meta.output.documents[*].text}}）；span 别名不可用。session 作用域解析 session payload {session_id, traces: [...]}，用 {{traces[*].spans[*]...}}（如 {{traces[*].spans[meta.span.kind:llm].meta.output.messages[*].content}}）；span 别名和 trace 作用域的顶层 {{spans[...]}} 不可用。数组选择器语法：[N] 索引、[START,END] 闭区间、[*] 通配、[field.path:value] 过滤；字符串数组换行连接，对象数组紧凑 JSON，空切片空字符串，隐式扇出，不支持负索引。
31. trace 作用域评测器示例（用户 prompt 体，配静态 System prompt）：goal_completion（filter @parent_id:undefined @meta.span.kind:agent，prompt "User goal:\n{{spans[0].meta.input.value}}\n\nAgent steps:\n{{spans}}"）；tool_use_correctness（同 filter，prompt 含 {{spans[meta.span.kind:tool].meta.input.parameters}} 和 {{spans[*].meta.output.value}}）；rag_faithfulness（filter @parent_id:undefined，prompt 含 {{spans[meta.span.kind:retrieval].meta.output.documents[*].text}} 和 {{spans[meta.span.kind:llm].meta.output.value}}）；conversation_quality（filter @parent_id:undefined，prompt 含 {{spans[meta.span.kind:llm].meta.input.messages[*].content}} 和 {{spans[meta.span.kind:llm].meta.output.messages[*].content}}）。
32. session 作用域评测器示例（filter 匹配会话 root span，如 @meta.span.kind:agent）：session_goal_completion（prompt "Session traces (chronological):\n{{traces}}"）；multi_turn_conversation_quality（prompt 含 {{traces[*].spans[meta.span.kind:llm].meta.input.messages[*].content}} 和 {{traces[*].spans[meta.span.kind:llm].meta.output.messages[*].content}}）；user_frustration_signals（prompt "Full session:\n{{traces}}"）；agent_consistency_across_session（prompt "Session traces (chronological):\n{{traces}}"）。
33. output_schema 包装格式（所有 provider 必需）：不是裸 JSON Schema，须用 OpenAI json_schema 对象形状。name 是固定类型判别符（boolean_eval/score_eval/categorical_eval），不是评测器名；schema.properties 内的属性键须与 name 完全一致；required 数组只能是 ["<type_key>"] 或 ["<type_key>", "reasoning"]；始终包含 "reasoning": {"type": "string"}。Boolean 用 assessment_criteria {"pass_when": true}；Score 用 {"min_threshold": 7}（可加 max_threshold）；Categorical 用 {"pass_values": ["correct"]} 且属性用 "type": "string" 加 anyOf（每个 const 是字符串值）。自定义/多维不直接支持，尽量实现为 score 或 categorical 或拆成多个评测器。
34. filter 作用域：提议针对特定 span kind 时转为 EVP filter 查询（如 @meta.span.kind:llm、service:checkout-agent）；仅当目标是 trace root 时才配合 root_spans_only:true。trace 作用域：每个完成 trace 触发一次（3 分钟不活动窗口后），晚到 span（>3 分钟）被排除；filter 须匹配 trace 的 root span（始终含 @parent_id:undefined 或 root_spans_only:true）；sampling_percentage 默认 5。session 作用域：仅当 sessions_present 时发布；每个完成会话触发一次（30 分钟不活动后），晚到 span（>30 分钟）被排除，超大会话上限 10000 span；filter 匹配会话 root span（无需 @parent_id:undefined）；sampling_percentage 默认 5 并标记为最重作用域。
35. 始终以草稿发布（enabled: false）：无论 integration_account_id 是否自动检测到，始终用 enabled: false 创建/更新评测器。UI 是激活的唯一来源，skill 绝不自动启用。用户在 UI 中审查每个草稿、确认集成账户正确后翻转开关。
36. integration_account_id 解析：绝不向用户索要原始 UUID。1) 从现有评测器继承——Phase 0 对每个现有自定义评测器调用 get_llmob s_evaluator 时检查 llm_provider.integration_account_id 字段，若有值则用同一 ID；多个不同 ID 时选最常见的并注明。2) 若无现有评测器有该字段则省略，草稿渲染时无预选账户，用户在 UI 审查时选择。
37. 发布（单条消息并行）：所有 create_or_update_llmobs_evaluator 调用在单条消息中发起（每个评测器一个）。telemetry.intent 设为简短英文描述如 "skill:agent-observability-eval-bootstrap — Bootstrap evaluator suite for ml_app=<ml_app> from production trace analysis."。任何调用失败则捕获错误继续其余评测器，绝不静默中止批次，在摘要中明确报告失败。
38. 发布摘要：含 Published Evaluators (drafts — pending UI review) 标题、说明所有发布为草稿需在 UI 审查激活、表格（#/Name/Action/Provider-Model/Sampling/Scope/Account auto-detected/Status）、错误列表、未发布的代码类评测器说明、下一步（在 UI 中打开草稿、验证集成账户、浏览 prompt 模板和 schema、用测试面板对真实数据试运行、启用、等待首次评分、调整采样/过滤、如需离线代码可要求重新生成已确认套件）。
39. Phase 3D 数据集模式（--emit-dataset <path> 触发，跳过 Phase 0 步骤 4、Phase 1、Phase 2）：调用 search_llmobs_spans(query="@ml_app:\"<ml_app>\" @status:ok", root_spans_only=true, limit=<trace-limit>, from=<timeframe>) 采样；对每个采样 root span 调用 get_llmobs_span_details（按 trace_id 分组）和 get_llmobs_span_content 读取 input/output，单条消息并行。
40. Phase 3D 记录提取：每个采样 root span 构建一个 DatasetRecordRaw——input_data 取 root span 的 meta.input（纯字符串则包为 {"input": "<value>"}，有 messages 则用 {"messages": [...]}，RAG root 有 documents 则含 {"documents": [...]}）；expected_output 取 meta.output.value（或 LLM-kind root 的 meta.output.messages[-1].content），这是生产行为基线非 ground truth；metadata 含 source/trace_id/span_id/ml_app/extracted_at；tags 用 ["env:prod", "source:traces", "ml_app:<ml_app>"]（始终 "key:value" 字符串）。
41. Phase 3D PII 清洗：写入前对所有字符串值运行 email/phone/SSN/API-key 正则替换为 <REDACTED:pii-type>，在摘要中列出受影响记录索引。
42. Phase 3D 标签规范化（强制预写步骤）：SDK 的 Dataset.append() 调用 validate_tags_list 拒绝任何无 : 分隔符的标签。写入 JSON 前对每条记录的 tags 列表规范化：1) 丢弃非字符串、None、空字符串；2) 已是 key:value（含 : 且两半非空）保留；3) 裸字符串（无 :）包为 "tag:<value>"（如 "interactive" → "tag:interactive"），绝不静默丢弃；4) 前导/尾随 : （如 "foo:"、":bar"）包为 "tag:<完整原始字符串>"。记录规范化次数并在摘要中一行说明。规范化后若任何记录 tags 仍含非 key:value 字符串则不写数据集。
43. Phase 3D 跳过记录：meta.output 为空或缺失（无可用基线）；root span 的 I/O 纯结构性（如只有工具调用无自然语言输出）。记录跳过数并在摘要中说明。
44. Phase 3D 写入：用 Write 工具把 JSON 数组（2 空格缩进）写到用户通过 --emit-dataset <path> 提供的路径（逐字使用）。此模式不推送到 Datadog——发布由调用方（onboarding 编排器或用户）通过 LLMObs.create_dataset(records=...) 处理。
45. Phase 3D 摘要：含 Generated Dataset 标题、路径、记录数、统计表（Records emitted/Records skipped/PII redactions applied/Tag normalizations applied）、重要说明（expected_output 是当前生产行为基线非 ground truth，用于回归式实验）、下一步（审查、用 LLMObs.create_dataset 发布到 Datadog 的 Python 代码示例、通过 agent-observability-experiment-bootstrap --dataset-name 运行实验）。此模式跳过 notebook 导出提示。
46. 操作规则：广度优先于精度，让用户裁剪——提议 8-15 个评测器分布在领域特定（最大桶）、结果、格式、安全；每个领域特定提议至少有一个观察 trace 模式支撑，无证据不发明通用领域评测器。不要过拟合——写能泛化到采样 trace 之外的准则。展示工作——每个提议评测器引用至少一个 trace 作为证据并给可点击链接 [Trace {first_8}...](https://app.datadoghq.com/llm/traces?query=trace_id:{full_32_char_id})。仅新建文件——绝不修改现有评测器代码或实验配置。诚实面对不确定性——少于 5 个 trace 支撑的提议评测器标记为 tentative。session 作用域受门控——仅当 Phase 1 探测确认 sessions_present 时才提议或发布 eval_scope: session 评测器；会话缺失则跳过并说明，绝不发布无法触发的 session 评测器。
47. pup 模式工具参考：spans search 用 `pup llm-obs spans search --query "@ml_app:A [other_filters]" [--from F] [--to T] [--limit N] [--cursor C] [--root-spans-only] [--span-kind K] [--summary]`（始终用 --query "@ml_app:A" 过滤，--ml-app 标志不可靠会静默返回其他应用的 span）；spans get-details 用 `pup llm-obs spans get-details --trace-id T --span-ids S1,S2,...`；spans get-content 用 `pup llm-obs spans get-content --trace-id T --span-id S --field F [--path P]`；spans get-trace 用 `pup llm-obs spans get-trace --trace-id T [--include-tree]`；spans get-agent-loop 用 `pup llm-obs spans get-agent-loop --trace-id T [--span-id S]`；spans find-errors 用 `pup llm-obs spans find-errors --trace-id T`；spans expand 用 `pup llm-obs spans expand --trace-id T --span-ids S1,S2,... [--max-depth N] [--filter-kind K]`。
48. pup 模式评测器工具：evals list 用 `pup llm-obs evals list`（客户端按 ml_app 过滤）；evals list-by-ml-app 用 `pup llm-obs evals list-by-ml-app --ml-app A`；evals get-evaluator 用 `pup llm-obs evals get-evaluator EVAL_NAME`；evals get-aggregate-stats 用 `pup llm-obs evals get-aggregate-stats EVAL_NAME [--ml-app A] [--from F] [--to T]`；evals delete 用 `pup llm-obs evals delete EVAL_NAME`；evals create-or-update 用 `pup llm-obs evals create-or-update EVAL_NAME --file /tmp/eval_EVAL_NAME.json`。
49. pup 模式 create_or_update_llmobs_evaluator 用扁平 JSON（所有字段顶层），get-evaluator 返回嵌套对象。转换：1) 先调 `pup llm-obs evals get-evaluator EVAL_NAME` 做往返检查，存在则从配置开始；2) 扁平化 llm_provider——把 integration_provider/model_name/integration_account_id/temperature 提升到顶层，删除 llm_provider 键；3) 合并并设 enabled: false；4) 写到临时文件并调用 `pup llm-obs evals create-or-update EVAL_NAME --file /tmp/eval_EVAL_NAME.json`，并行发布多个评测器时用唯一临时文件名（如 /tmp/eval_toxicity.json）。
50. pup 模式 notebook：create 用 `pup notebooks create --title "TITLE" --file /tmp/nb_cells.json`（用 `pup notebooks create --help` 确认确切标志）；edit 用 `pup notebooks edit NOTEBOOK_ID --file /tmp/nb_cells.json`（取当前 notebook 追加提供的 cell 写回）。cells 文件是 JSON 数组：[{"attributes": {"definition": {"type": "markdown", "text": "## Section\n\nContent."}}, "type": "notebook_cells"}]。
51. MCP 结果解析安全：在写任何迭代或访问 MCP 工具结果字段的脚本（Python、jq 等）前，先检查原始结构——检查 type(result)、顶层键、payload 是否嵌套在 content block 内（如 [{'type': 'text', 'text': '<json>'}]）。需要时提取并 json.loads() 内层 payload 再解析。绝不假设 MCP 结果是裸 dict 或 list。

适用边界 · 注意事项

• 需要 Datadog LLM Observability 的 MCP 服务器或 pup CLI 才能运行（publish 模式还需 Datadog 账户和 LLM 集成账户），两者都不可用时无法执行。
• data_only 模式跳过评测覆盖映射和去重，因为没有 Datadog 评测项目可对照。
• session 作用域评测器仅在采样 span 携带 session_id（且理想情况下跨多个 trace）时才提议或发布，否则无法触发。