Sentry JavaScript SDK 新增 AI Provider 集成开发指南:Instrumentation、模式选型与实现清单

原创2026-09-24 13:11:481,714 阅读
文章标签:可观测性

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 特别提示两点"参考文件看不出来的事实":

  1. 一个 Provider 可能同时需要两种模式:vercelAIIntegration 既订阅 ai >= 7 的原生 ai:telemetry channel,又为 v4–v6 运行 Orchestrion 注入,两套通道在同一个集成里并存(见 index.ts 中 instrumentVercelAiOrchestrion 订阅 orchestrion:ai:* 注入 channel)。
  2. 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(CJS require)与 .mjs(ESM import)双份构建产物,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 列出了七条硬性规则,每一条都在仓库源码中得到印证:

  1. 从结果形状而非 params.stream 判断流式调用。异步可迭代对象或 SDK 自身的 stream 对象才是判据;只有手动调用 instrument{Provider}Client() API 时才以 params.stream === true 为准。参考 openai.ts:wrapStreamResult 用 isAsyncIterable(result) 检查 data.result,命中后把 Symbol.asyncIterator 原地替换为 instrumentStream 包装的迭代器,并把 span 结束权交给流。

  2. 绝不要手工设置流式响应属性。流式场景先把数据累积进 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。

  3. 绝不截断消息负载。v11 中截断逻辑已被移除(对应 PR #23045),下游没有任何容量限制,大小限制完全由服务端处理。

  4. 绝不把子 span 的 token 用量回滚累加到父 span。树的汇总由产品端基于完整 span 树计算。

  5. 绝不直接读取 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>;
}
  1. 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)。

  2. 设置 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 的贡献流程标准化、可复制。

登录后查看全文
sentry-javascript