docs(llma): migrate onboarding docs to OpenTelemetry auto-instrumentation

[richardsolomou]

Problem

The in-app LLM analytics onboarding docs currently show PostHog SDK wrappers (posthog.ai.openai, @posthog/ai) as the primary integration method. We're moving toward standard OpenTelemetry auto-instrumentation as the recommended approach, keeping the wrappers available as a last resort for users who need them.

Changes

Migrates 28 provider onboarding guides from PostHog SDK wrapper approach to OpenTelemetry auto-instrumentation. Each migrated doc follows a consistent 3-step pattern:

1. Install dependencies — OTel SDK + provider-specific instrumentation + provider SDK
2. Set up OpenTelemetry tracing — TracerProvider with OTLPSpanExporter (Python) or PostHogTraceExporter (Node)
3. Call the provider — Native SDK usage, no posthog_ parameters

User identification uses the posthog.distinct_id resource attribute; custom properties like foo and conversation_id demonstrate the passthrough behavior.

Providers migrated (21 original + 7 more):

• OpenAI-compatible: openai, groq, deepseek, mistral, cohere, fireworks-ai, xai, hugging-face, openrouter, together-ai, ollama, cerebras, perplexity
• AI gateways: portkey, helicone, vercel-ai-gateway
• Azure OpenAI, Anthropic
• Frameworks: langchain, langgraph, llamaindex
• Vercel AI (SimpleSpanProcessor update)
• Newly migrated: autogen, instructor, mirascope, semantic-kernel, smolagents, pydantic-ai (already OTel-based in examples — docs just hadn't caught up)
• Mastra (migrated to @mastra/posthog exporter — Mastra's native integration since there's no mature OTel path yet)

Kept as-is: google (no Node.js OTel instrumentation for @google/genai), aws-bedrock (already OTel), crewai, litellm, dspy, openai-agents, manual

Migration callout: Every migrated doc has a callout at the top linking to the full Node.js and Python examples on GitHub (current main/master), plus legacy wrapper examples pinned to the last commit before the migration. This helps both new users (who see the recommended OTel path) and existing users (who can find the old wrapper examples they're already using).

Manual capture doc: Split into multiple steps so it can have a useful table of contents (Capture LLM events manually → Event properties → Verify traces and generations).

Removed: "No proxy" callouts from all migrated docs — they made sense when wrapping SDK clients but don't apply to standard OTel tracing.

How did you test this code?

Agent-authored PR. Manually verified:

• TypeScript compiles (pnpm --filter=@posthog/frontend format runs cleanly)
• Each migrated doc follows the same pattern as other OTel docs
• Example code in the docs matches what's in the real example repos (feat(examples): migrate AI examples to OpenTelemetry instrumentation posthog-js#3349 and feat(examples): migrate AI examples to OpenTelemetry instrumentation posthog-python#482)

No runtime tests since these are in-app onboarding content (static TSX returning step definitions).

Publish to changelog?

No

Docs update

This IS the docs update. Companion PR: PostHog/posthog.com#16236 (updates TOC frontmatter in posthog.com).

🤖 LLM context

Co-authored with Claude Code. Related PRs:

• feat(examples): migrate AI examples to OpenTelemetry instrumentation posthog-js#3349 (Node.js OTel examples)
• feat(examples): migrate AI examples to OpenTelemetry instrumentation posthog-python#482 (Python OTel examples)
• docs(llma): update TOC for OTel onboarding migration posthog.com#16236 (docs.posthog.com TOC updates)

[greptile-apps]

Vulnerabilities

No security concerns identified. The changes are documentation-only, migrating onboarding code snippets from PostHog SDK wrappers to OpenTelemetry auto-instrumentation. API keys in the snippets are clearly marked as placeholders.

Comments Outside Diff (1)

1. docs/onboarding/llm-analytics/portkey.tsx, line 24-43 (link)

   Missing portkey-ai package in install instructions

   The "Install dependencies" step only lists the OpenAI SDK and OTel packages, but the "Call Portkey" step imports portkey_ai (Python) and portkey-ai (Node) which are not included. Users copying the install command will hit an ImportError / Module not found error at runtime.

   Python step (line 136–141) uses:

   from portkey_ai import PORTKEY_GATEWAY_URL

   Node step (line 158) uses:

   import { PORTKEY_GATEWAY_URL } from 'portkey-ai'

   The install blocks should include portkey-ai:

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/onboarding/llm-analytics/portkey.tsx
   Line: 24-43
   
   Comment:
   **Missing `portkey-ai` package in install instructions**
   
   The "Install dependencies" step only lists the OpenAI SDK and OTel packages, but the "Call Portkey" step imports `portkey_ai` (Python) and `portkey-ai` (Node) which are not included. Users copying the install command will hit an `ImportError` / `Module not found` error at runtime.
   
   Python step (line 136–141) uses:
   ```python
   from portkey_ai import PORTKEY_GATEWAY_URL
   ```
   
   Node step (line 158) uses:
   ```typescript
   import { PORTKEY_GATEWAY_URL } from 'portkey-ai'
   ```
   
   The install blocks should include `portkey-ai`:
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/onboarding/llm-analytics/portkey.tsx
Line: 24-43

Comment:
**Missing `portkey-ai` package in install instructions**

The "Install dependencies" step only lists the OpenAI SDK and OTel packages, but the "Call Portkey" step imports `portkey_ai` (Python) and `portkey-ai` (Node) which are not included. Users copying the install command will hit an `ImportError` / `Module not found` error at runtime.

Python step (line 136–141) uses:
```python
from portkey_ai import PORTKEY_GATEWAY_URL
```

Node step (line 158) uses:
```typescript
import { PORTKEY_GATEWAY_URL } from 'portkey-ai'
```

The install blocks should include `portkey-ai`:

```suggestion
                    <Markdown>Install the OpenTelemetry SDK, the OpenAI instrumentation, the OpenAI SDK, and the Portkey SDK.</Markdown>

                    <CodeBlock
                        blocks={[
                            {
                                language: 'bash',
                                file: 'Python',
                                code: dedent`
                                    pip install openai portkey-ai opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-openai-v2
                                `,
                            },
                            {
                                language: 'bash',
                                file: 'Node',
                                code: dedent`
                                    npm install openai portkey-ai @posthog/ai @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/instrumentation-openai
                                `,
                            },
                        ]}
                    />
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix(llma): address review feedback on OT..." | Re-trigger Greptile}

[github-actions]

Docs from this PR will be published at posthog.com

Project	Deployment	Preview	Updated (UTC)
posthog.com	🤷 Unknown	Preview	Apr 9, 2026, 8:16 AM

Preview will be ready in ~10 minutes. Click Preview link above to access docs at /handbook/engineering/