接入上报

三步接好埋点和错误监控。chatkit 自己不发任何请求，数据交给你的埋点 SDK。

1. 接入

import {
  Chatkit,
  ChatkitProvider,
  createTelemetry,
  useChatSessions,
} from '@volcengine/chatkit';

const telemetry = createTelemetry({
  track: sdk.track, // (name, props) => void
  beacon: sdk.beacon, // 同上，页面关闭时用
  reportError: monitor.report, // (error, ctx) => void
  attributes: {
    common: () => ({ version: APP_VERSION }),
  },
});

const sessions = useChatSessions({
  adapter,
  activeSessionId,
  ...telemetry.sessionOptions,
});

<ChatkitProvider sessions={sessions} {...telemetry.props}>
  <Chatkit />
</ChatkitProvider>;

填什么	说明
`track`	你的埋点 SDK
`beacon`	页面关闭时用的上报通道，通常基于 `navigator.sendBeacon`。要给，不给的话关页面那一轮会丢，中断率偏低
`reportError`	你的错误监控。只在这里接一次，会话列表和会话 hook 的错误也交到这里
`attributes`	你的维度：版本、场景、实验分组。别放用户输入

createTelemetry 写在模块级或 useMemo 里。

2. 会收到什么

默认每轮对话一条 turn_summary，外加几个诊断事件。属性已经拍平成一层，可以直接入库。

事件	什么时候	关键字段
`turn_summary`	每轮对话结束	`outcome`、`effective`、`firstPaintMs`、`totalMs`、`errorCode`、`background`
`render_error`	一条消息渲染崩了	`scope`、`errorName`
`history_loaded`	打开会话拉历史	`ok`、`durationMs`
`send_result`	发送失败时	`reason`

每条都带 sessionId、runId、eventId 和你在 attributes 里给的维度。outcome 是这一轮的结论： completed（有回答）、empty（没回答）、failed（失败）、interrupted（中途断了）、aborted（用户点了停止）。

3. 看板怎么算

同一轮可能有两条 turn_summary（先中断、后恢复），按 sessionId + runId 取 revision 最大的一条。

指标	算法
会话完成率	`outcome = completed` 的轮数 ÷ `effective = true` 的轮数
空回复率	`outcome = empty` 的轮数 ÷ `effective = true` 的轮数
任务失败率	`outcome = failed` 的轮数 ÷ `effective = true` 的轮数，按 `errorCode` 拆
回复中断率	`outcome = interrupted` 的轮数 ÷ `effective = true` 的轮数
用户中止率	`outcome = aborted` 的轮数 ÷ 全部轮数
首字延迟	`firstPaintMs` 的 P50 / P90，排除 `background = true`
会话完成耗时	`outcome = completed` 的 `totalMs` 的 P50 / P90
工具调用成功率	（`toolCalls_total` − `toolCalls_failed` − `toolCalls_cancelled`）÷（`toolCalls_total` − `toolCalls_cancelled`），按轮求和后再除

前四个加起来正好 100%。耗时看分位数，不看平均值。

上线前检查

用 Mock 适配器的 telemetry-acceptance 场景发五句话（第五句点停止），然后检查上报：

import { verifyTelemetry }
  from '@volcengine/chatkit/testing';

const { problems } = verifyTelemetry(track.mock.calls, {
  requiredAttributes: ['version'],
});
expect(problems).toEqual([]);

它会检查每种结论都有、你的维度都带上了、没有对话内容、没有重复上报。

开发时还可以在页面上放 @volcengine/chatkit/devtools 的 ChatkitTelemetryInspector，实时看指标算出来是多少。

想了解更多

全部事件、字段、错误来源、自己写上报层：事件
每个指标的完整口径、排除规则、常见问题：指标

#接入上报

#1. 接入

#2. 会收到什么

#3. 看板怎么算