Sentry JavaScript SDK 新增 AI Provider 集成开发指南:Instrumentation、模式选型与实现清单
Sentry JavaScript SDK 新增 AI Provider 集成开发指南:Instrumentation、模式选型与实现清单
本文基于 sentry-javascript 仓库中面向贡献者的内部技能文档
add-ai-integration编写,系统地讲解如何为 Sentry JavaScript SDK 新增一个 AI Provider(OpenAI、Anthropic、Vercel AI、LangChain、Google GenAI、Mastra 等)的追踪集成。你将掌握:三种接入模式的选型逻辑(原生 tracing channel / Orchestrion 注入 channel / 回调与 exporter)、代码在仓库中的落位规则、七条核心陷阱(Gotchas),以及一份可直接对照执行的实现 Checklist。读完即可对照现有集成(如 openai、vercel-ai、langchain)动手接入新 Provider。
前置原则:Span Ops 与 Attributes 由仓库外部规范定义
SKILL 文档开篇就强调 "Conventions First":gen_ai 相关的 span op 与属性名不允许在集成代码里自行发明或硬编码,必须引用 Sentry 官方约定(conventions):
- 规范性来源是 gen_ai attributes 与 gen_ai ops,在代码中通过
@sentry/conventions/attributes与@sentry/conventions/op导入; - RFC 0153 解释了 Sentry 的生成式 AI 约定为何与 OpenTelemetry 的 OTel gen-ai semconv 分道扬镳。
在仓库源码中可以找到大量佐证。例如 OpenAI 集成 直接从 @sentry/core 导入 SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,而 Vercel AI 的 channel 订阅器 一口气从 @sentry/conventions/attributes 导入了 GEN_AI_INPUT_MESSAGES、GEN_AI_OUTPUT_MESSAGES、GEN_AI_USAGE_INPUT_TOKENS、GEN_AI_USAGE_OUTPUT_TOKENS、GEN_AI_USAGE_TOTAL_TOKENS 等一整套属性常量,并从 @sentry/conventions/op 导入 GEN_AI_EMBEDDINGS、GEN_AI_GENERATE_CONTENT、GEN_AI_EXECUTE_TOOL、GEN_AI_INVOKE_AGENT、GEN_AI_RERANK 等 op 常量。
由此引出一条派生规则:
不要手工挑选 span op,统一通过
getGenAiSpanOp()从 ai/core/utils.ts 派生。
该函数的实现体现了"未知操作不得伪装成约定"的设计:
// packages/server-utils/src/ai/core/utils.ts
const NON_INFERENCE_OPERATIONS = new Set(['unknown']);
export function getGenAiSpanOp(operationName: string): string {
return NON_INFERENCE_OPERATIONS.has(operationName) ? FUNCTION : `gen_ai.${operationName}`;
}
即推理类操作生成 gen_ai.<operation> 形式的 op,而非推理的兜底 unknown 落到通用 function op,避免让一个未知字符串冒充 gen_ai 约定。以 OpenAI 集成 为例,chat/embeddings 两个 channel 的 span 都是通过 getGenAiSpanOp(operation) 派生 op。
另一个排序原则是:
ai/core/gen-ai-attributes.ts 只用于兜底——它保存的是
@sentry/conventions中没有对应项的"缺口填充"键,所以最后再检查它,而不是第一个。
从源码看,该文件确实只存放了少量无 conventions 等价物的常量,如 gen_ai.request.stream、gen_ai.request.encoding_format、gen_ai.request.dimensions、gen_ai.response.stop_reason、gen_ai.tool.call.id,并注明"Based on OpenTelemetry Semantic Conventions for Generative AI"。
三种接入模式选型:Pattern 1 / 2 / 3
SKILL 提供了一张选型决策树,核心问题是:目标 SDK 是否发布了它自己的 diagnostics_channel 遥测?
Does the SDK publish its own `diagnostics_channel` telemetry?
|- YES (ai >= 7) -> Pattern 1: Native tracing channel
+- NO -> Does the SDK expose callback/exporter hooks?
|- YES (LangChain, Mastra) -> Pattern 3: Callback/Exporter
+- NO (OpenAI, Anthropic, Google GenAI, ai < 7) -> Pattern 2: Orchestrion-injected channels
| Pattern | 适用场景 | 参考实现 |
|---|---|---|
| 1 — 原生 tracing channel | SDK 自身向 diagnostics_channel 发布遥测 |
integrations/vercel-ai/vercel-ai-dc-subscriber.ts |
| 2 — Orchestrion 注入 channel | SDK 没有自己的遥测机制 | integrations/openai.ts + orchestrion/config/openai.ts |
| 3 — 回调 / exporter | SDK 暴露回调钩子或 exporter | ai/langchain/、ai/mastra/(exporter 形态的 agent 框架) |
Pattern 1:订阅原生 tracing channel(Vercel AI v7 示例)
vercelAIIntegration 在 setupOnce() 阶段就通过 waitForTracingChannelBinding 订阅 ai:telemetry channel;在 vercel-ai-dc-subscriber.ts 中可以看到该 channel 的常量定义:
// packages/server-utils/src/integrations/vercel-ai/vercel-ai-dc-subscriber.ts
const AI_SDK_TELEMETRY_TRACING_CHANNEL = 'ai:telemetry';
SKILL 特别提示两点"参考文件看不出来的事实":
- 一个 Provider 可能同时需要两种模式:
vercelAIIntegration既订阅ai>= 7 的原生ai:telemetrychannel,又为 v4–v6 运行 Orchestrion 注入,两套通道在同一个集成里并存(见 index.ts 中instrumentVercelAiOrchestrion订阅orchestrion:ai:*注入 channel)。 - Pattern 1 的订阅者可以无条件注册:对从不发布遥测的 SDK 版本,订阅天然是 no-op,因此可以放心地在
setupOnce里直接挂订阅。
Pattern 2:Orchestrion 注入 channel(OpenAI 示例)
当 SDK 没有任何遥测机制时(OpenAI、Anthropic、Google GenAI、ai < 7),Sentry 通过 Orchestrion 在构建期/运行期把 tracing channel 注入目标库的方法,再由集成订阅这些注入的 channel。以 OpenAI 为例:
- orchestrion/config/openai.ts 声明了要注入的模块与函数:chat completions、responses API、embeddings、conversations 的
create方法,并区分.js(CJSrequire)与.mjs(ESMimport)双份构建产物,version range 为>=4.0.0 <8; - 对应的 channel 名定义在同文件末尾的
openaiChannels中:orchestrion:openai:chat与orchestrion:openai:embeddings; - openai.ts 中的
instrumentOpenai()用bindTracingChannelToSpan把 channel 绑定到 span 生命周期,并通过invokeOrchestrionInstrumentation(client, openaiModuleNames, instrumentOpenai, [options])完成注入。
该集成的 JSDoc 也明确写到:它"requires the Sentry runtime hook or bundler plugin"——这正是 SKILL Checklist 中要求 Pattern 2 文档注明的前提条件。
Pattern 3:回调 / exporter(LangChain、Mastra 示例)
对于暴露回调钩子或 exporter 形态的 agent 框架(LangChain、Mastra),不需要 Orchestrion 注入,直接在 ai/langchain/ 与 ai/mastra/ 目录里实现回调/exporter 订阅逻辑,再在 src/integrations/ 里封装成集成。
代码落位:Instrumentation、Integration 与运行时再导出
新增集成时,代码严格按三层落位:
| 层级 | 位置 | 说明 |
|---|---|---|
| Instrumentation | packages/server-utils/src/ai/{provider}/ |
与 Provider SDK 交互的插桩逻辑、流处理、属性累积 |
| Integration | packages/server-utils/src/integrations/{provider}.ts |
封装成 Sentry 集成(defineIntegration),负责订阅 channel / 触发注入 |
| 运行时再导出 | node、cloudflare、bun 等运行时包 |
只做 re-export,从不自行定义实现 |
例外:Workers AI 是客户端包装,位于 packages/cloudflare/src/instrumentations/worker/instrumentEnv.ts。它通过 Proxy 包装 Cloudflare 的 env 对象,在属性访问时用鸭子类型探测绑定类型;当命中 isAiBinding(item)(run + gateway + toMarkdown 鸭子类型)时,调用 instrumentWorkersAiClient(item) 返回插桩后的 Workers AI 客户端(instrumentEnv.ts)。
从 ai 目录结构 可以看到,Instrumentation 每个 Provider 拥有独立子目录(anthropic-ai、google-genai、langchain、langgraph、mastra、mistral、openai、vercel-ai、workers-ai、flue 等),且多数包含 constants.ts、types.ts、utils.ts、index.ts,流式 Provider 还有专门的 streaming.ts(如 ai/openai/streaming.ts、ai/anthropic-ai/streaming.ts);integrations 目录 则统一存放 openai.ts、anthropic.ts、google-genai.ts、langchain.ts、langgraph.ts、mastra.ts、vercel-ai/、groq.ts、together-ai.ts、mistral.ts 等集成文件。
七条 Gotchas:新增 AI 集成必须绕开的陷阱
SKILL 列出了七条硬性规则,每一条都在仓库源码中得到印证:
-
从结果形状而非
params.stream判断流式调用。异步可迭代对象或 SDK 自身的 stream 对象才是判据;只有手动调用instrument{Provider}Client()API 时才以params.stream === true为准。参考 openai.ts:wrapStreamResult用isAsyncIterable(result)检查data.result,命中后把Symbol.asyncIterator原地替换为instrumentStream包装的迭代器,并把 span 结束权交给流。 -
绝不要手工设置流式响应属性。流式场景先把数据累积进
StreamResponseState,再调用endStreamSpan()统一收尾——异步生成器参考 ai/openai/streaming.ts,监听器式流参考 ai/anthropic-ai/streaming.ts。endStreamSpan的共享实现位于 ai/core/utils.ts,它会设置gen_ai.response.streaming、response id/model、token 用量(有显式 total 用之,否则由 prompt/completion/cache token 求和)、finish reasons,并按recordOutputs决定是否写入响应文本与 tool calls。 -
绝不截断消息负载。v11 中截断逻辑已被移除(对应 PR #23045),下游没有任何容量限制,大小限制完全由服务端处理。
-
绝不把子 span 的 token 用量回滚累加到父 span。树的汇总由产品端基于完整 span 树计算。
-
绝不直接读取
dataCollection.genAI。输入/输出记录的开关必须走resolveAIRecordingOptions()。该函数实现于 ai/core/utils.ts,优先级为:显式选项 >dataCollection.genAI> 默认true:
export function resolveAIRecordingOptions<T extends GenAiOptions>(options?: T): T & Required<GenAiOptions> {
const genAI = getClient()?.getDataCollectionOptions().genAI;
return {
...options,
recordInputs: options?.recordInputs ?? genAI?.inputs ?? true,
recordOutputs: options?.recordOutputs ?? genAI?.outputs ?? true,
} as T & Required<GenAiOptions>;
}
-
LangChain 必须在
getTracingIntegrations()中第一个注册,这样它可以在各 Provider 集成动手插桩前禁用它们。在 integrations/index.ts 中,AI Providers 区块的注释明确写着 "LangChain must come first to disable AI provider integrations before they instrument",随后才是 langChain、langGraph、mastra、vercelAI、openAI、anthropicAI、googleGenAI、mistral、groq、togetherAI。机制上,OpenAI 集成在createGenAiSpan开头检查_INTERNAL_shouldSkipAiProviderWrapping(INTEGRATION_NAME),命中即跳过开 span,避免 LangChain 驱动时产生重复 span(openai.ts)。 -
设置
SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN = 'auto.ai.{provider}',且取值只能包含字母数字、_、.。例如 OpenAI 集成定义为const ORIGIN = 'auto.ai.openai';(openai.ts),Vercel AI channel 订阅器为'auto.vercelai.channel'(vercel-ai-dc-subscriber.ts)。
新增集成的完整 Checklist
SKILL 给出了一份可直接勾选的验收清单,逐条对照即可完成一次符合规范的集成贡献:
- [ ] Instrumentation 放在
src/ai/,集成放在src/integrations/,并在getTracingIntegrations()中注册(LangChain 排在最前); - ] 从 [packages/server-utils/src/index.ts 导出,并由受支持的运行时包(node、cloudflare、bun、deno 等)再导出;
- ] 在 [dev-packages/node-integration-tests/suites/tracing/{provider}/ 编写 E2E 测试(Cloudflare 亦支持时,补充
cloudflare-integration-tests/);从目录列表看,仓库已为 anthropic、google-genai、groq、langchain、langgraph、mastra、mistral、openai、together-ai、vercelai 等建立了对应测试套件目录; - [ ] ops 与 attributes 取自
@sentry/conventions,op 通过getGenAiSpanOp()派生; - [ ] 记录开关由
resolveAIRecordingOptions()门控;无截断、无 token 回滚; - [ ] JSDoc 中写明:订阅的 channel 名称、支持的 SDK 版本,以及 Pattern 2 需要 Sentry runtime hook 或 bundler plugin 的前提;
- [ ] 只在目标包被实际 import 后才打补丁(未被使用则为零成本)。
最后,SKILL 给出了兜底建议:拿不准时,就照着最相似的既有集成做("When in doubt, follow the pattern of the most similar existing integration.")。这正是整个 add-ai-integration 技能的核心方法论:以约定为准绳、以既有集成为模板、以 Checklist 为验收,从而把新增 AI Provider 的贡献流程标准化、可复制。