references/instructor.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Instructor AI Observability installation
Canonical URL: https://posthog.com/docs/ai-observability/installation/instructor
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install dependencies
- Set up OpenTelemetry tracing
- Extract structured data
- Users and sessions
- Verify traces and generations
- Next steps
Let AI instrument your LLM calls for you
Skip the manual setup — run this in your project and the wizard installs the SDK and wires up AI Observability for you.
npx @posthog/wizard ai-observability
PostHog Wizard hedgehog
Let AI instrument your LLM calls for you
-
1
Install dependencies
Required
Full working examples
See the complete Node.js and Python examples on GitHub. If you use the PostHog SDK wrapper instead of OpenTelemetry: see the Node.js wrapper and Python wrapper examples instead.
Install the OpenTelemetry SDK, the OpenAI instrumentation, and Instructor.
Python
pip install instructor openai opentelemetry-sdk "posthog[otel]" opentelemetry-instrumentation-openai-v2Node
npm install @instructor-ai/instructor openai zod @posthog/ai @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/instrumentation-openai -
2
Set up OpenTelemetry tracing
Required
Configure OpenTelemetry to auto-instrument OpenAI SDK calls and export traces to PostHog. PostHog converts
gen_ai.*spans into$ai_generationevents automatically.Python
from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.resources import Resource, SERVICE_NAME from posthog.ai.otel import PostHogSpanProcessor from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor resource = Resource(attributes={ SERVICE_NAME: "my-app", "posthog.distinct_id": "user_123", # optional: identifies the user in PostHog "foo": "bar", # custom properties are passed through }) provider = TracerProvider(resource=resource) provider.add_span_processor( PostHogSpanProcessor( api_key="<ph_project_token>", host="https://us.i.posthog.com", ) ) trace.set_tracer_provider(provider) OpenAIInstrumentor().instrument()Node
import { NodeSDK } from '@opentelemetry/sdk-node' import { resourceFromAttributes } from '@opentelemetry/resources' import { PostHogSpanProcessor } from '@posthog/ai/otel' import { OpenAIInstrumentation } from '@opentelemetry/instrumentation-openai' const sdk = new NodeSDK({ resource: resourceFromAttributes({ 'service.name': 'my-app', 'posthog.distinct_id': 'user_123', // optional: identifies the user in PostHog foo: 'bar', // custom properties are passed through }), spanProcessors: [ new PostHogSpanProcessor({ projectToken: '<ph_project_token>', host: 'https://us.i.posthog.com', }), ], instrumentations: [new OpenAIInstrumentation()], }) sdk.start() -
3
Extract structured data
Required
Use Instructor to extract structured data from LLM responses. PostHog automatically captures an
$ai_generationevent for each call made through the OpenAI SDK that Instructor wraps.Python
import instructor import openai from pydantic import BaseModel class User(BaseModel): name: str age: int client = instructor.from_openai(openai.OpenAI(api_key="your_openai_api_key")) user = client.chat.completions.create( model="gpt-4o-mini", response_model=User, messages=[{"role": "user", "content": "Extract: John is 30 years old"}], ) print(user)Node
import OpenAI from 'openai' import Instructor from '@instructor-ai/instructor' import { z } from 'zod' const oai = new OpenAI({ apiKey: 'your_openai_api_key' }) const client = Instructor({ client: oai, mode: 'TOOLS' }) const UserSchema = z.object({ name: z.string(), age: z.number(), }) const user = await client.chat.completions.create({ model: 'gpt-4o-mini', response_model: { schema: UserSchema, name: 'User' }, messages: [{ role: 'user', content: 'Extract: John is 30 years old' }], }) console.log(user)Note: To capture LLM events anonymously, omit the
posthog.distinct_idresource attribute and don't set a distinct ID in the PostHog context. See our docs on anonymous vs identified events to learn more.You can expect captured
$ai_generationevents to have the following properties:| Property | Description | | --- | --- | |
$ai_model| The specific model, likegpt-5-miniorclaude-4-sonnet| |$ai_latency| The latency of the LLM call in seconds | |$ai_time_to_first_token| Time to first token in seconds (streaming only) | |$ai_tools| Tools and functions available to the LLM | |$ai_input| List of messages sent to the LLM | |$ai_input_tokens| The number of tokens in the input (often found in response.usage) | |$ai_output_choices| List of response choices from the LLM | |$ai_output_tokens| The number of tokens in the output (often found inresponse.usage) | |$ai_total_cost_usd| The total cost in USD (input + output) | | [...] | See full list of properties | -
4
Users and sessions
Recommended
A server usually handles requests for many users, so a resource attribute can't say who each trace belongs to. Wrap each request in a PostHog context instead. The PostHog span processor adds the context's distinct ID and properties to every AI span started inside it. Other span processors and exporters on the same provider don't see them.
Set
$ai_session_idif your product has multi-turn conversations, so the Sessions tab can group their traces. Workloads that finish in a single trace, like batch jobs or one-shot generation, don't need it.Python
# Requires posthog 7.70.0 or later import posthog with posthog.new_context(): posthog.identify_context(user_id) posthog.tag("$ai_session_id", conversation_id) posthog.tag("plan", "pro") # custom properties work too reply = handle_turn(user_message)Node
// Requires @posthog/ai 8.14.0 and posthog-node 5.15.0 or later import { PostHog } from 'posthog-node' const posthog = new PostHog('<ph_project_token>', { host: 'https://us.i.posthog.com' }) const sdk = new NodeSDK({ // ...the rest of your setup from the earlier step spanProcessors: [ new PostHogSpanProcessor({ projectToken: '<ph_project_token>', host: 'https://us.i.posthog.com', client: posthog, }), ], }) const reply = await posthog.withContext( { distinctId: userId, properties: { $ai_session_id: conversationId, plan: 'pro', // custom properties work too }, }, () => handleTurn(userMessage) )On Node, install
posthog-nodeand pass the client as theclientoption of yourPostHogSpanProcessor. Without it, the processor doesn't read the context.A distinct ID set this way takes priority over a
posthog.distinct_idresource attribute, so you can keep the resource attribute as the fallback for work outside a request. If your instrumentation already sets thegen_ai.conversation.idattribute, PostHog uses it as the session ID, and an explicit$ai_session_idtakes priority over it. -
Verify traces and generations
Recommended
Confirm LLM events are being sent to PostHog
Let's make sure LLM events are being captured and sent to PostHog. Under AI Observability, you should see rows of data appear in the Traces and Generations tabs.
LLM generations in PostHog
-
5
Next steps
Recommended
Now that you're capturing AI conversations, continue with the resources below to learn what else AI Observability enables within the PostHog platform.
| Resource | Description | | --- | --- | | Basics | Learn the basics of how LLM calls become events in PostHog. | | Generations | Read about the
$ai_generationevent and its properties. | | Traces | Explore the trace hierarchy and how to use it to debug LLM calls. | | Spans | Review spans and their role in representing individual operations. | | Anaylze LLM performance | Learn how to create dashboards to analyze LLM performance. |