feat(ai): replace otel client-side span mapping with PostHogTraceExporter (#3232)

* Replace otel client-side span mapping with PostHogTraceExporter

Replace the PostHogSpanProcessor (which did client-side span mapping
via posthog-node) with PostHogTraceExporter, a thin wrapper around
OTLPTraceExporter that points to PostHog's /i/v0/ai/otel endpoint.

PostHog now handles gen_ai.* span conversion to $ai_generation events
server-side, so the client no longer needs the mapper pipeline.

* fix(ai): address PR review feedback

Use URL.origin for trailing slash handling instead of regex, add inline
comment on auth header, consolidate tests into it.each, add changeset.

* fix(ai): add apiKey validation, clean up unused deps, improve tests

Remove @opentelemetry/sdk-trace-base from peer and dev dependencies
since it's no longer imported after the exporter rewrite. Add apiKey
validation to PostHogTraceExporter constructor. Assert on mock
constructor args instead of internal _config in tests.

* switch to gpt-5-mini

* fix otel for convex

Author: richardsolomou

.changeset/otel-trace-exporter.md

@@ -0,0 +1,5 @@
+---
+'@posthog/ai': minor
+---
+
+Replace otel client-side span mapping with PostHogTraceExporter. PostHog now converts gen_ai.* spans into $ai_generation events server-side, so the client-side mapper pipeline (PostHogSpanProcessor, captureSpan, aiSdkSpanMapper) has been replaced with a simple OTLPTraceExporter wrapper.

examples/example-convex/convex/aiSdk/manualCapture.ts

@@ -18,7 +18,7 @@ export const generate = action({
     const startTime = Date.now()
 
     const result = await generateText({
-      model: openai('gpt-4o-mini'),
+      model: openai('gpt-5-mini'),
       prompt: args.prompt,
     })
 
@@ -33,7 +33,7 @@ export const generate = action({
 
         // Core identification
         $ai_provider: 'openai',
-        $ai_model: 'gpt-4o-mini',
+        $ai_model: 'gpt-5-mini',
 
         // Token usage
         $ai_input_tokens: result.usage.inputTokens,

examples/example-convex/convex/aiSdk/openTelemetry.ts

@@ -1,46 +1,37 @@
 "use node"
 
 import { NodeSDK } from '@opentelemetry/sdk-node'
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
 import { resourceFromAttributes } from '@opentelemetry/resources'
 import { generateText } from 'ai'
 import { openai } from '@ai-sdk/openai'
+import { PostHogTraceExporter } from '@posthog/ai/otel'
 import { action } from '../_generated/server'
 import { v } from 'convex/values'
 
 // Demonstrates using the Vercel AI SDK's experimental_telemetry with
-// PostHog's native OTel endpoint to automatically capture $ai_generation events.
+// PostHog's PostHogTraceExporter to automatically capture $ai_generation events.
 export const generate = action({
   args: {
     prompt: v.string(),
     distinctId: v.optional(v.string()),
   },
   handler: async (_ctx, args) => {
-    // Set up an OTel SDK that exports spans directly to PostHog's
-    // /i/v0/ai/otel endpoint. PostHog converts gen_ai.* spans into
-    // $ai_generation events server-side. NodeSDK (vs NodeTracerProvider)
-    // handles context propagation via AsyncLocalStorage automatically,
-    // which the AI SDK needs to connect parent and child spans.
-    const exporter = new OTLPTraceExporter({
-      url: `${process.env.POSTHOG_HOST || 'https://us.i.posthog.com'}/i/v0/ai/otel`,
-      headers: {
-        Authorization: `Bearer ${process.env.POSTHOG_API_KEY}`,
-      },
-    })
-
     const distinctId = args.distinctId ?? 'anonymous'
 
     const sdk = new NodeSDK({
       resource: resourceFromAttributes({
         'service.name': 'example-convex',
         'user.id': distinctId,
       }),
-      traceExporter: exporter,
+      traceExporter: new PostHogTraceExporter({
+        apiKey: process.env.POSTHOG_API_KEY!,
+        host: process.env.POSTHOG_HOST,
+      }),
     })
     sdk.start()
 
     const result = await generateText({
-      model: openai('gpt-4o-mini'),
+      model: openai('gpt-5-mini'),
       prompt: args.prompt,
       experimental_telemetry: {
         isEnabled: true,

examples/example-convex/convex/aiSdk/withTracing.ts

@@ -28,7 +28,7 @@ export const generate = action({
   handler: async (_ctx, args) => {
     // Wrap the model with PostHog tracing — this automatically captures
     // $ai_generation events with token usage, latency, and content.
-    const model = withTracing(openai('gpt-4o-mini'), phClient as unknown as WithTracingPostHog, {
+    const model = withTracing(openai('gpt-5-mini'), phClient as unknown as WithTracingPostHog, {
       posthogDistinctId: args.distinctId,
     })
 

examples/example-convex/convex/convexAgent/manualCapture.ts

@@ -7,7 +7,7 @@ import { posthog } from '../posthog.js'
 
 const supportAgent = new Agent(components.agent, {
   name: 'support-agent',
-  languageModel: openai('gpt-4o-mini'),
+  languageModel: openai('gpt-5-mini'),
   instructions: 'You are a helpful support agent. Answer questions concisely.',
 })
 

examples/example-convex/convex/convexAgent/openTelemetry.ts

@@ -1,49 +1,40 @@
 "use node"
 
 import { NodeSDK } from '@opentelemetry/sdk-node'
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
 import { resourceFromAttributes } from '@opentelemetry/resources'
 import { Agent } from '@convex-dev/agent'
 import { openai } from '@ai-sdk/openai'
+import { PostHogTraceExporter } from '@posthog/ai/otel'
 import { components } from '../_generated/api'
 import { action } from '../_generated/server'
 import { v } from 'convex/values'
 
 // Demonstrates using @convex-dev/agent with the Vercel AI SDK's
-// experimental_telemetry and PostHog's native OTel endpoint to
+// experimental_telemetry and PostHog's PostHogTraceExporter to
 // automatically capture $ai_generation events.
 export const generate = action({
   args: {
     prompt: v.string(),
     distinctId: v.optional(v.string()),
   },
   handler: async (ctx, args) => {
-    // Set up an OTel SDK that exports spans directly to PostHog's
-    // /i/v0/ai/otel endpoint. PostHog converts gen_ai.* spans into
-    // $ai_generation events server-side. NodeSDK (vs NodeTracerProvider)
-    // handles context propagation via AsyncLocalStorage automatically,
-    // which the AI SDK needs to connect parent and child spans.
-    const exporter = new OTLPTraceExporter({
-      url: `${process.env.POSTHOG_HOST || 'https://us.i.posthog.com'}/i/v0/ai/otel`,
-      headers: {
-        Authorization: `Bearer ${process.env.POSTHOG_API_KEY}`,
-      },
-    })
-
     const distinctId = args.distinctId ?? 'anonymous'
 
     const sdk = new NodeSDK({
       resource: resourceFromAttributes({
         'service.name': 'example-convex',
         'user.id': distinctId,
       }),
-      traceExporter: exporter,
+      traceExporter: new PostHogTraceExporter({
+        apiKey: process.env.POSTHOG_API_KEY!,
+        host: process.env.POSTHOG_HOST,
+      }),
     })
     sdk.start()
 
     const supportAgent = new Agent(components.agent, {
       name: 'support-agent',
-      languageModel: openai('gpt-4o-mini'),
+      languageModel: openai('gpt-5-mini'),
       instructions: 'You are a helpful support agent. Answer questions concisely.',
     })
 

examples/example-convex/convex/convexAgent/withTracing.ts

@@ -29,7 +29,7 @@ export const generate = action({
   handler: async (ctx, args) => {
     // Wrap the model with PostHog tracing before passing it to the agent.
     // Every LLM call the agent makes will automatically capture $ai_generation events.
-    const model = withTracing(openai('gpt-4o-mini'), phClient as unknown as WithTracingPostHog, {
+    const model = withTracing(openai('gpt-5-mini'), phClient as unknown as WithTracingPostHog, {
       posthogDistinctId: args.distinctId,
     })
 

packages/ai/README.md

@@ -24,7 +24,7 @@ const client = new OpenAI({
 })
 
 const completion = await client.chat.completions.create({
-  model: 'gpt-3.5-turbo',
+  model: 'gpt-5-mini',
   messages: [{ role: 'user', content: 'Tell me a fun fact about hedgehogs' }],
   posthogDistinctId: 'user_123', // optional
   posthogTraceId: 'trace_123', // optional
@@ -39,61 +39,44 @@ console.log(completion.choices[0].message.content)
 await phClient.shutdown()
 ```
 
-## OTEL + AI SDK (`experimental_telemetry`)
+## OpenTelemetry
 
-Use this when working with Vercel AI SDK telemetry. `@posthog/ai` exposes an OTEL `SpanProcessor` that maps spans to PostHog AI events and sends them through `posthog-node`.
+`@posthog/ai` provides a `PostHogTraceExporter` that sends OpenTelemetry traces to PostHog's OTLP ingestion endpoint. PostHog converts `gen_ai.*` spans into `$ai_generation` events server-side. This works with any LLM provider SDK that supports OpenTelemetry.
+
+```bash
+npm install @posthog/ai @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
+```
 
 ```typescript
 import { NodeSDK } from '@opentelemetry/sdk-node'
-import { PostHog } from 'posthog-node'
 import { generateText } from 'ai'
 import { openai } from '@ai-sdk/openai'
-import { PostHogSpanProcessor } from '@posthog/ai/otel'
-
-const phClient = new PostHog('<YOUR_PROJECT_API_KEY>', { host: 'https://us.i.posthog.com' })
+import { PostHogTraceExporter } from '@posthog/ai/otel'
 
 const sdk = new NodeSDK({
-  spanProcessors: [
-    new PostHogSpanProcessor(phClient),
-  ],
+  traceExporter: new PostHogTraceExporter({
+    apiKey: '<YOUR_PROJECT_API_KEY>',
+    host: 'https://us.i.posthog.com', // optional, defaults to https://us.i.posthog.com
+  }),
 })
-
 sdk.start()
 
-await generateText({
-  model: openai('gpt-5.1'),
+const result = await generateText({
+  model: openai('gpt-5-mini'),
   prompt: 'Write a short haiku about debugging',
   experimental_telemetry: {
     isEnabled: true,
     functionId: 'my-awesome-function',
     metadata: {
+      posthog_distinct_id: 'user_123',
       conversation_id: 'abc123',
-      plan: 'pro',
     },
   },
 })
 
-await phClient.shutdown()
+await sdk.shutdown()
 ```
 
-### Custom Mappers
-
-The OTEL processor supports adapter mappers for different span formats:
-
-- `aiSdkSpanMapper` is the default mapper.
-- You can pass custom `mappers` in `PostHogSpanProcessor` options to support additional span schemas.
-
-### Per-call Metadata (Recommended)
-
-For dynamic properties, pass values in `experimental_telemetry.metadata` on each AI SDK call.
-These are captured from `ai.telemetry.metadata.*` and forwarded as PostHog event properties.
-Use processor options (`posthogProperties`) only for global defaults.
-
-## Notes
-
-- The OTEL route currently maps supported spans into PostHog AI events (manual capture path).
-- Existing wrapper-based tracing (for example `withTracing`) still works and is unchanged.
-
 LLM Observability [docs](https://posthog.com/docs/ai-engineering/observability)
 
 Please see the main [PostHog docs](https://www.posthog.com/docs).

packages/ai/package.json

@@ -24,7 +24,7 @@
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.8",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
     "@babel/preset-env": "catalog:",
     "@babel/preset-typescript": "catalog:",
     "@posthog-tooling/rollup-utils": "workspace:*",
@@ -58,15 +58,15 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
     "@ai-sdk/provider": "^2.0.0 || ^3.0.0",
     "posthog-node": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
     },
-    "@opentelemetry/sdk-trace-base": {
+    "@opentelemetry/exporter-trace-otlp-http": {
       "optional": true
     },
     "@ai-sdk/provider": {

packages/ai/src/index.ts

@@ -1,7 +1,7 @@
 import PostHogOpenAI from './openai'
 import PostHogAzureOpenAI from './openai/azure'
 import { wrapVercelLanguageModel } from './vercel/middleware'
-import { PostHogSpanProcessor, createPostHogSpanProcessor, captureSpan } from './otel'
+import { PostHogTraceExporter } from './otel'
 import PostHogAnthropic from './anthropic'
 import PostHogGoogleGenAI from './gemini'
 import { LangChainCallbackHandler } from './langchain/callbacks'
@@ -12,6 +12,6 @@ export { PostHogAzureOpenAI as AzureOpenAI }
 export { PostHogAnthropic as Anthropic }
 export { PostHogGoogleGenAI as GoogleGenAI }
 export { wrapVercelLanguageModel as withTracing }
-export { PostHogSpanProcessor, createPostHogSpanProcessor, captureSpan }
+export { PostHogTraceExporter }
 export { LangChainCallbackHandler }
 export { Prompts }