接入 OTel：在浏览器里看每轮调用瀑布图

一条评估用例跑了 40 秒，你想知道时间花在哪：是模型想得慢，还是某个工具调用卡住了。终端只告诉你这一轮总共花了多久。调用瀑布图能回答这个问题。它在 niceeval view 里按轮列出每一次模型调用和工具执行，以及各自的耗时和 token。如果你的应用已经在发 OTel trace，这份数据你其实已经有了。AI SDK 的 telemetry、LangGraph 导出到 LangSmith 的 trace、OpenLLMetry 或 OpenInference 的自动埋点，以及你自己按 GenAI 语义埋的点都算。让应用把 span 也发给 NiceEval 一份就行，应用的业务代码不用改，仍属于无侵入接入，见 Tier。瀑布图只用来看，不参与判分。t.calledTool、t.maxTokens 这些断言仍然读取 Adapter 在 send 里返回的事件和用量。span 缺失或迟到只会让瀑布图不完整，不会改变通过与否。

span 从哪来、到哪去

运行评估时，NiceEval 在本机启动一个 OTLP 接收器。应用发来的 span 按 send 轮次分好，统一成 GenAI 语义，和这个 Attempt 的结果一起保存，niceeval view 再据此画瀑布图。span 不参与断言，不影响 Agent 的行为、执行错误或判定。埋点缺失、span 迟到或丢了一批，只会让瀑布图不完整。

把 span 发给 NiceEval

接入分三处改动：Adapter 带上每轮的 trace 头，应用知道往哪发，应用的埋点打开导出。 1. Adapter 带上 traceparent。 send 照常写，事件映射不变，只多一行：把这一轮的 traceparent 随请求发给应用。

// agents/support-bot.ts
import { completeEvidenceCoverage, defineAgent } from "niceeval/adapter";

export default defineAgent({
  name: "support-bot",
  evidenceCoverage: completeEvidenceCoverage,
  async send(input, ctx) {
    // 示例地址：换成你自己 agent 的真实端点
    const r = await fetch("http://localhost:5188/chat", {
      method: "POST",
      // traceparent 随请求带过去:本轮 span 挂到 NiceEval 的 trace 下,并发下归属才精确
      headers: { "content-type": "application/json", ...ctx.telemetry?.headers },
      body: JSON.stringify({ message: input.text, model: ctx.model }),
      signal: ctx.signal,
    });
    const body = await r.json();
    return {
      status: r.ok ? "completed" : "failed",
      events: mapToEvents(body),   // 断言的依据在这里,和没接 OTel 时一样
    };
  },
});

用 uiMessageStreamAgent 时不用写这一行，它会自动把 ctx.telemetry.headers 加进请求头。 2. 告诉应用往哪发。 接收地址在应用启动时配置，不经过 send。标准 OTel SDK 只在进程启动时读一次 OTEL_* 环境变量。按应用的运行方式选择：

你自己启动、一直在跑的服务（最常见）：在 niceeval.config.ts 里固定接收端口。写了这个配置，就打开了 OTel 接入：
// niceeval.config.ts export default defineConfig({ telemetry: { port: 4318 }, // 接收器固定监听 http://localhost:4318/v1/traces });
服务启动时设一次 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces，之后跑多少次评估用例都不用改。用 OTel Collector 转发时，也指向这个地址。端口是固定的，所以同一台机器同时只能跑一个 niceeval 进程。端口被其它进程占用时，NiceEval 会直接报错，提示你换一个空闲端口。告诉应用的接收地址默认是 127.0.0.1。只有应用要经过隧道或其它路由才能访问到运行 NiceEval 的机器时，才用 host 写出那个地址，例如 telemetry: { host: "otel.internal", port: 4318 }。Docker Sandbox Agent 默认在同一个 Sandbox 内启动接收器，不需要容器连回宿主机。OTLP 接收只通过这两个字段配置，不读环境变量。
由 NiceEval 启动的子进程（CLI 型 Agent）：什么都不用做。把 ctx.telemetry.env（标准 OTEL_* 环境变量，可直接展开）放进进程环境即可。每次运行都是新进程，读到的就是这次的地址。

3. 打开应用埋点的导出。 按你用的埋点库，各加几行配置：

AI SDK
LangGraph / LangChain
OpenLLMetry
OpenInference
自己埋的 gen_ai

推荐官方 OTel 集成（@ai-sdk/otel，产标准 GenAI 语义）。老的 experimental_telemetry（ai.*）也能画：

import { generateText } from "ai";

const result = await generateText({
  model, tools, messages,
  experimental_telemetry: { isEnabled: true },
});

exporter 走标准 OTel Node SDK，endpoint 指向 NiceEval（注入的 env 或固定端口）。可跑示例：应用侧埋点见 examples/zh/origin/ai-sdk-v7（src/backend/otel.ts，官方 @ai-sdk/otel），接入后的完整评测项目见 examples/zh/tier1/ai-sdk-v7。

零依赖路线，三个环境变量：

LANGSMITH_TRACING=true \
LANGSMITH_OTEL_ENABLED=true \
LANGSMITH_OTEL_ONLY=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces \
node server.js   # 端点值按「向应用提供端点」一节选择：注入的 env 或固定端口

LANGSMITH_OTEL_ONLY 表示只发 OTLP、不发 LangSmith 云端。需要双发时移除该变量。Python 版 langsmith SDK 会在 import 时自动注册 OTel hook。JS 版（langsmith@0.7.x）还需要显式调用 langsmith/experimental/otel/setup 导出的 initializeOTEL()，否则只输出警告，不产生 span。三个环境变量保持不变。Python 后端示例见 examples/zh/origin/langgraph，完整评测项目见 examples/zh/tier1/langgraph。

import * as traceloop from "@traceloop/node-server-sdk";

traceloop.initialize({ disableBatch: true });
// endpoint 用标准 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量

from openinference.instrumentation.langchain import LangChainInstrumentor
from phoenix.otel import register

register()  # 或标准 OTel SDK;endpoint 走 OTEL_EXPORTER_OTLP_ENDPOINT
LangChainInstrumentor().instrument()

按 OTel GenAI 语义约定埋：模型调用 span 名 chat {model}，工具 span 名 execute_tool {tool}，属性带 gen_ai.operation.name、gen_ai.tool.name / gen_ai.tool.call.id。这是 NiceEval 归一的目标语义，画出来的瀑布图最完整。

把 span 归属到 Turn

并行跑多条评估用例时，同一个接收器会同时收到多条会话的 span。NiceEval 用两种方式把它们分到各自的轮次：

按 traceparent（推荐，并发也准）：send 发请求时把 ctx.telemetry.headers 展开进请求头，每轮带一个新的 traceparent。应用埋点支持 trace context 传播时（标准 OTel HTTP 服务端埋点都支持），这一轮的 span 会挂到 NiceEval 给的 trace 下，按 traceId 准确对上。
按时间（备用）：应用不传播 trace context 时，按 send 开始和结束的时间判断。这种方式只在逐个执行时可靠，所以 NiceEval 会让这个 Agent 的轮次逐个执行，并在日志里提示，不会把不同会话的 span 混在一起。确认 traceparent 生效后，自动恢复并发。

应用要及时导出 span。用 SimpleSpanProcessor，或每轮结束时 flush。BatchSpanProcessor 会缓冲一阵再发，span 可能晚到下一轮，瀑布图偶尔缺尾巴多半是这个原因。

保留现有 OTel 后端并双发

应用多半已经把 trace 发给自己的观测后端，例如 Langfuse、SigNoz 或生产环境的 collector。接 NiceEval 不用换后端，也不用第二套埋点。TracerProvider 可以挂多个 SpanProcessor，同一批 span 发往两处：

// instrumentation.ts —— 应用启动时初始化一次:一份埋点,两个出口
import { NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

export const provider = new NodeTracerProvider({
  spanProcessors: [
    // 出口 1:你自己的后端,一直发
    new SimpleSpanProcessor(new OTLPTraceExporter({ url: process.env.MY_COLLECTOR_URL })),
    // 出口 2:NiceEval。线上没有这个变量时,这个出口根本不存在——线上线下同一份代码
    ...(process.env.OTEL_EXPORTER_OTLP_ENDPOINT
      ? [new SimpleSpanProcessor(new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }))]
      : []),
  ],
});
provider.register();

不方便改应用代码时，用 OTel Collector 转发：应用只发给 collector，collector 配两个 exporter，一个指向你的后端，一个指向 NiceEval 的固定地址。代价是多维护一个组件。

用语义映射控制瀑布图内容

瀑布图里一条 span 显示成模型调用、工具执行还是子 Agent，取决于它带了什么属性。NiceEval 画图前把每条 span 统一到 GenAI 语义，主要看 gen_ai.operation.name（标准操作名）和统一后的 kind：

Span 语义	瀑布图内容
`gen_ai.operation.name: "chat"`（或 `text_completion` / `embeddings`）	按模型调用着色分类
`gen_ai.operation.name: "execute_tool"`，或属性里有 `tool_name`	按工具执行着色分类
`gen_ai.operation.name: "invoke_agent"` / `"create_agent"`	按子 Agent 着色分类
属性 `call_id` 等于 `send` 返回事件里的 `operationId`	这条工具 span 自动补上真实入参和出参（`io.input` / `io.output`，取自 `send` 返回的事件。很多埋点默认不采集内容，也不影响这一点）
span 状态 = error	红色标错
什么都没有（统一成 `other`）	仍在时间线上显示。trace 超过 150 条 span 时会被折叠
其余属性	原样保留，在 `niceeval view` 里点开 span 查看

应用直接按 GenAI 语义约定埋点（上文「自己埋的 gen_ai」）时，这些都自动成立。AI SDK、LangSmith、OpenLLMetry / OpenInference 的常见 span 也能被自动识别。

私有埋点：自己写映射

瀑布图里全是灰色的 other，通常是应用用了自己的 span 命名，自动识别认不出。有两种办法：

改埋点（推荐）：在应用里给 span 加一个 gen_ai.operation.name 属性。改动只有一行，你自己的观测后端也能受益。
写 spanMapper：不方便改应用时，在 Agent 上声明一个纯函数，画图前把自定义 span 翻译成上表的语义。tagSpan 把分类写回 span，只添加属性、不改原有属性；heuristicTag 是自动识别用的同一套判断。两者都从 niceeval/adapter 导出：

import { completeEvidenceCoverage, defineAgent, tagSpan, heuristicTag } from "niceeval/adapter";
import type { TraceSpan } from "niceeval";

function mapMySpans(spans: TraceSpan[]): TraceSpan[] {
  return spans.map((span) => {
    // 私有命名 → 标准语义:op 写进 gen_ai.operation.name,kind 定着色
    if (span.name === "my.llm.request") return tagSpan(span, { op: "chat", kind: "model" });
    if (span.name === "my.tool.exec") {
      // 把私有调用 id 映射成 call_id，使工具 I/O 能与 send 事件关联
      const attributes = { ...span.attributes, call_id: String(span.attributes?.["my.callId"] ?? "") };
      return tagSpan({ ...span, attributes }, { op: "execute_tool", kind: "tool" });
    }
    return tagSpan(span, heuristicTag(span));   // 其余交给自动识别
  });
}

export default defineAgent({
  name: "my-agent",
  evidenceCoverage: completeEvidenceCoverage,
  spanMapper: mapMySpans,
  async send(input, ctx) { /* 同上文接法 */ },
});

niceeval/adapter 导出的 mapCodexSpans 是一个可以参考的 spanMapper 实现。spanMapper 只影响瀑布图。映射写错只会让分类或颜色不准，不影响断言。

检查结果

跑完一次评估，用 pnpm exec niceeval view 打开浏览器，进入某个 Attempt 查看每一轮的瀑布图。终端里用 pnpm exec niceeval show @<locator> 查看这个 Attempt 的结果和日志提示。

瀑布图为空：整次运行一条 span 都没收到，通常是应用没连上接收地址，例如环境变量没设上，或改了配置后服务没重启。NiceEval 会在日志里提示，断言照常判定。
瀑布图偶尔缺尾巴：先查应用是否用了 BatchSpanProcessor，见上文「把 span 归属到 Turn」。
span 都显示成 other：见上文「私有埋点：自己写映射」。

OTel 接入不负责的事

断言的数据全部来自 send。工具调用要映射进 events（用内置转换器或手写映射，见编写 Send），用量要放进 send 的返回值。只出现在 span 里、events 里没有的数据，不参与断言。
多轮会话和 HITL 照常在 send 里做。span 不表达“等人输入”，会话续接也由应用接口决定（会话续接见编写 Send，HITL 见 HITL）。

开始使用

接入你的应用

写好评估用例

评估 Coding Agent

实验与对比

看结果与迭代

提速：并发与复用

基础设施与 CI

问题排查

接入 OTel：在浏览器里看每轮调用瀑布图

span 从哪来、到哪去

把 span 发给 NiceEval

把 span 归属到 Turn

保留现有 OTel 后端并双发

用语义映射控制瀑布图内容

私有埋点：自己写映射

检查结果

OTel 接入不负责的事

相关阅读

​span 从哪来、到哪去

​把 span 发给 NiceEval

​把 span 归属到 Turn

​保留现有 OTel 后端并双发

​用语义映射控制瀑布图内容

​私有埋点：自己写映射

​检查结果

​OTel 接入不负责的事

​相关阅读

span 从哪来、到哪去

把 span 发给 NiceEval

把 span 归属到 Turn

保留现有 OTel 后端并双发

用语义映射控制瀑布图内容

私有埋点：自己写映射

检查结果

OTel 接入不负责的事

相关阅读