add-ai-integration

Adding a New AI Integration

Decision Tree

Does the AI SDK have native OpenTelemetry support?
|- YES -> Does it emit OTel spans automatically?
|   |- YES (like Vercel AI) -> Pattern 1: OTel Span Processors
|   +- NO -> Pattern 2: OTel Instrumentation (wrap client)
+- NO -> Does the SDK provide hooks/callbacks?
    |- YES (like LangChain) -> Pattern 3: Callback/Hook Based
    +- NO -> Pattern 4: Client Wrapping

Runtime-Specific Placement

If an AI SDK only works in one runtime, code lives exclusively in that runtime's package. Do NOT add it to packages/core/.

• Node.js-only -> packages/node/src/integrations/tracing/{provider}/
• Cloudflare-only -> packages/cloudflare/src/integrations/tracing/{provider}.ts
• Browser-only -> packages/browser/src/integrations/tracing/{provider}/
• Multi-runtime -> shared core in packages/core/src/tracing/{provider}/ with runtime-specific wrappers

Span Hierarchy

• gen_ai.invoke_agent — parent/pipeline spans (chains, agents, orchestration)
• gen_ai.chat, gen_ai.generate_text, etc. — child spans (actual LLM calls)

Shared Utilities (packages/core/src/tracing/ai/)

• gen-ai-attributes.ts — OTel Semantic Convention attribute constants. Always use these, never hardcode.
• utils.ts — setTokenUsageAttributes(), getTruncatedJsonString(), truncateGenAiMessages(), buildMethodPath()
• Only use attributes from Sentry Gen AI Conventions.

Streaming

• Non-streaming: startSpan(), set attributes from response
• Streaming: startSpanManual(), accumulate state via async generator or event listeners, set GEN_AI_RESPONSE_STREAMING_ATTRIBUTE: true, call span.end() in finally block
• Detect via params.stream === true
• References: openai/streaming.ts (async generator), anthropic-ai/streaming.ts (event listeners)

Token Accumulation

• Child spans: Set tokens directly from API response via setTokenUsageAttributes()
• Parent spans (invoke_agent): Accumulate from children using event processor (see vercel-ai/)

Pattern 1: OTel Span Processors

Use when: SDK emits OTel spans automatically (Vercel AI)

1. Core: Create add{Provider}Processors() in packages/core/src/tracing/{provider}/index.ts — registers spanStart listener + event processor
2. Node.js: Add callWhenPatched() optimization in packages/node/src/integrations/tracing/{provider}/index.ts — defers registration until package is imported
3. Edge: Direct registration in packages/cloudflare/src/integrations/tracing/{provider}.ts — no OTel, call processors immediately

Reference: packages/node/src/integrations/tracing/vercelai/

Pattern 2: OTel Instrumentation (Client Wrapping)

Use when: SDK has no native OTel support (OpenAI, Anthropic, Google GenAI)

1. Core: Create instrument{Provider}Client() in packages/core/src/tracing/{provider}/index.ts — Proxy to wrap client methods, create spans manually
2. Node.js instrumentation.ts: Patch module exports, wrap client constructor. Check _INTERNAL_shouldSkipAiProviderWrapping() for LangChain compatibility.
3. Node.js index.ts: Export integration function using generateInstrumentOnce() helper

Reference: packages/node/src/integrations/tracing/openai/

Pattern 3: Callback/Hook Based

Use when: SDK provides lifecycle hooks (LangChain, LangGraph)

1. Core: Create create{Provider}CallbackHandler() — implement SDK's callback interface, create spans in callbacks
2. Node.js instrumentation.ts: Auto-inject callbacks by patching runnable methods. Disable underlying AI provider wrapping.

Reference: packages/node/src/integrations/tracing/langchain/

Auto-Instrumentation (Node.js)

Mandatory for Node.js AI integrations. OTel only patches when the package is imported (zero cost if unused).

Steps

1. Add to getAutoPerformanceIntegrations() in packages/node/src/integrations/tracing/index.ts — LangChain MUST come first
2. Add to getOpenTelemetryInstrumentationToPreload() for OTel-based integrations
3. Export from packages/node/src/index.ts: integration function + options type
4. Add E2E tests:
   • Node.js: dev-packages/node-integration-tests/suites/tracing/{provider}/
   • Cloudflare: dev-packages/cloudflare-integration-tests/suites/tracing/{provider}/
   • Browser: dev-packages/browser-integration-tests/suites/tracing/ai-providers/{provider}/

Key Rules

1. Respect dataCollection.genAI for recording input and output messages
2. Set SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN = 'auto.ai.{provider}' (alphanumerics, _, . only)
3. Truncate large data with helper functions from utils.ts
4. gen_ai.invoke_agent for parent ops, gen_ai.chat for child ops

Checklist

• Runtime-specific code placed only in that runtime's package
• Added to getAutoPerformanceIntegrations() in correct order (Node.js)
• Added to getOpenTelemetryInstrumentationToPreload() (Node.js with OTel)
• Exported from appropriate package index
• E2E tests added and verifying auto-instrumentation
• Only used attributes from Sentry Gen AI Conventions
• JSDoc says "enabled by default" or "not enabled by default"
• Documented how to disable (if auto-enabled)
• Verified OTel only patches when package imported (Node.js)

Reference Implementations

• Pattern 1 (Span Processors): packages/node/src/integrations/tracing/vercelai/
• Pattern 2 (Client Wrapping): packages/node/src/integrations/tracing/openai/
• Pattern 3 (Callback/Hooks): packages/node/src/integrations/tracing/langchain/

When in doubt, follow the pattern of the most similar existing integration.