Custom properties

Contents

Custom properties in AI Observability enable you to add metadata to your AI generations, making it easier to filter, analyze, and understand your LLM usage patterns.

This guide shows you how to set custom properties using PostHog's AI Observability SDKs and leverage them for better observability. For specific integration patterns, see our guides on linking to session replay and linking to error tracking.

Why use custom properties?

Custom properties help you:

  • Filter traces by specific criteria (e.g., subscription tier, feature flags, account settings)
  • Track prompt versions to measure improvements over time
  • Link backend LLM events to session replays and error tracking
  • Group related generations by custom business logic (e.g, sessions, conversations, tenants )
  • Monitor costs by user segments or features

Setting custom properties

You can add custom properties to any LLM generation using the posthogProperties parameter (JavaScript) or posthog_properties parameter (Python). These properties will appear in the $ai_generation event alongside the automatically captured metrics in your PostHog dashboard.

Basic example

import { OpenAI } from '@posthog/ai'
import { PostHog } from 'posthog-node'
const phClient = new PostHog(
'<ph_project_token>',
{ host: 'https://us.i.posthog.com' }
)
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
posthog: phClient
})
const response = await openai.responses.create({
model: 'gpt-5',
messages: [{ role: 'user', content: 'Hello' }],
posthogProperties: {
customProperty: 'customValue',
conversationId: 'conv_abc123',
subscriptionTier: 'premium',
feature: 'chatAssistant'
}
})

Setting event options

On posthog-python 8.0 and @posthog/ai, the AI integrations also take event options, such as cookieless_mode, which control how PostHog processes an event. Pass them per call with posthogOptions (JavaScript) or posthog_options (Python), next to the custom properties:

const response = await openai.responses.create({
model: 'gpt-5',
input: 'Hello',
posthogDistinctId: 'user_123',
posthogOptions: { cookieless_mode: true }
})
  • In JavaScript, withTracing() takes posthogOptions too. The LangChain callback handler and the OpenAI Agents, Claude Agent SDK, Google ADK, and Genkit integrations take options when you set them up.
  • In Python, every wrapper method that takes posthog_properties also takes posthog_options, and the Gemini clients take it as a default for every call. LangChain's CallbackHandler and PostHogMiddleware, and the OpenAI Agents and Claude Agent SDK integrations, take options when you set them up. The $exception event LangChain captures for a failed run gets the same options.
  • These options win over context and global options.
  • An event without a distinct ID always has person processing turned off, whatever its options say.

Common use cases

1. Subscription tier tracking

Track LLM usage by subscription tier or payment plan to monitor costs and usage patterns:

const getSubscriptionTier = (userId) => {
// Your logic to determine the user subscription tier
return user.subscription?.tier || 'free'
}
const response = await openai.responses.create({
model: 'gpt-5',
messages: messages,
posthogDistinctId: userId,
posthogProperties: {
subscriptionTier: getSubscriptionTier(userId),
monthlyUsage: user.currentMonthUsage,
rateLimited: user.isRateLimited
}
})

2. Prompt versioning

Track different versions of your prompts to measure improvements:

const PROMPT_VERSION = "v2.3.1"
const PROMPT_ID = "customer_support_agent"
const systemPrompt = getPromptTemplate(PROMPT_ID, PROMPT_VERSION)
const response = await anthropic.messages.create({
model: 'claude-sonnet-4-0',
messages: [
{ role: 'system', content: systemPrompt },
{ role: 'user', content: userMessage }
],
posthogProperties: {
prompt_id: PROMPT_ID,
prompt_version: PROMPT_VERSION,
prompt_tokens: systemPrompt.length,
experiment_variant: 'detailed_instructions'
}
})

3. Custom generation names

Set meaningful names for your LLM generations to improve trace readability:

// For Vercel AI SDK
import { withTracing } from '@posthog/ai'
import { generateText } from 'ai'
const model = withTracing(
openaiClient('gpt-5'),
phClient,
{
posthogProperties: {
$ai_span_name: "Generate Product Description",
product_category: "electronics",
target_length: "short"
}
}
)
const { text } = await generateText({
model: model,
prompt: `Write a product description for: ${productName}`
})

The $ai_span_name property will appear as the primary label in your trace visualization, making it easier to identify specific operations.

Filtering in the dashboard

Once you've set custom properties, they appear in the PostHog AI Observability dashboard where you can:

  1. Filter generations by any custom property
  2. Create insights based on custom properties
  3. Build dashboards segmented by your custom fields

For example, after setting a conversation_id property, you can:

  • Filter the generations table to show only events from a specific conversation
  • Create a funnel to track conversation completion rates
  • Build a dashboard showing average cost per conversation by user subscription tier

Your custom properties will appear in the event details panel alongside the automatically captured properties like model, tokens, and latency.

Still have questions?

Was this page useful?