PostHog

PostHog is an analytics platform with AI observability features for monitoring LLM applications. The PostHog exporter sends your traces to PostHog as structured events, providing insights into token usage, costs, latency, and conversation flows.

Installation

npm

npm install @mastra/posthog@latest

pnpm

pnpm add @mastra/posthog@latest

Yarn

yarn add @mastra/posthog@latest

Bun

bun add @mastra/posthog@latest

Configuration

Prerequisites

1. PostHog Account: Sign up at posthog.com
2. Project API Key: Get your project API key from PostHog Settings → Project API Key
3. Environment Variables: Set your credentials

.env

# Required
POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx

# Optional
POSTHOG_HOST=https://us.i.posthog.com  # or eu.i.posthog.com for EU region

Zero-Config Setup

With environment variables set, use the exporter with no configuration:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { PosthogExporter } from '@mastra/posthog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      posthog: {
        serviceName: 'my-service',
        exporters: [new PosthogExporter()],
      },
    },
  }),
})

Explicit Configuration

You can also pass credentials directly (takes precedence over environment variables):

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { PosthogExporter } from '@mastra/posthog'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      posthog: {
        serviceName: 'my-service',
        exporters: [
          new PosthogExporter({
            apiKey: process.env.POSTHOG_API_KEY,
          }),
        ],
      },
    },
  }),
})

Configuration options

Complete Configuration

new PosthogExporter({
  // Required credentials
  apiKey: process.env.POSTHOG_API_KEY!,

  // Optional settings
  host: 'https://us.i.posthog.com', // Default: US region
  // or "https://eu.i.posthog.com" for EU region
  // or your self-hosted URL

  // Batching configuration
  flushAt: 20, // Batch size (default: 20)
  flushInterval: 10000, // Flush interval in ms (default: 10000)
  serverless: false, // Serverless mode: flushAt=10, flushInterval=2000

  // User identification
  defaultDistinctId: 'anonymous', // Fallback if no userId in metadata

  // Privacy settings
  enablePrivacyMode: false, // Excludes input/output from generation events

  // Diagnostic logging
  logLevel: 'info', // debug | info | warn | error
})

Serverless Mode

Optimized batching for serverless environments:

new PosthogExporter({
  apiKey: process.env.POSTHOG_API_KEY!,
  serverless: true, // Configures smaller batches for faster flushing
})

Privacy Mode

Exclude input/output data from generation events while preserving token metrics:

new PosthogExporter({
  apiKey: process.env.POSTHOG_API_KEY!,
  enablePrivacyMode: true, // Removes $ai_input and $ai_output_choices
})

Group analytics

To attach events to a PostHog group, add a $groups object to tracingOptions.metadata. The exporter sends those values as the top-level groups field on the PostHog capture call, so you can slice analytics such as LLM cost by group.

await agent.generate(input, {
  tracingOptions: {
    metadata: {
      $groups: {
        publication: 'publication-1',
      },
    },
  },
})

Related

• Tracing Overview
• PostHog Documentation