PosthogExporter

Sends Tracing data to PostHog for AI observability and analytics.

Constructor

new PosthogExporter(config: PosthogExporterConfig)

PosthogExporterConfig

interface PosthogExporterConfig extends BaseExporterConfig {
  apiKey?: string
  host?: string
  flushAt?: number
  flushInterval?: number
  serverless?: boolean
  defaultDistinctId?: string
  enablePrivacyMode?: boolean
}

Extends BaseExporterConfig, which includes:

• logger?: IMastraLogger - Logger instance
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Log level (default: INFO)

Methods

exportTracingEvent

async exportTracingEvent(event: TracingEvent): Promise<void>

Exports a tracing event to PostHog.

onFeedbackEvent

async onFeedbackEvent(event: FeedbackEvent): Promise<void>

Exports a feedback event to PostHog. See Feedback export.

flush

async flush(): Promise<void>

Force flushes any buffered events to PostHog without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.

shutdown

async shutdown(): Promise<void>

Flushes pending batched events and shuts down the PostHog client.

Usage

Zero-Config (using environment variables)

import { PosthogExporter } from '@mastra/posthog'

// Reads from POSTHOG_API_KEY, POSTHOG_HOST
const exporter = new PosthogExporter()

Explicit Configuration

import { PosthogExporter } from '@mastra/posthog'

const exporter = new PosthogExporter({
  apiKey: process.env.POSTHOG_API_KEY!,
  host: 'https://us.i.posthog.com',
  serverless: true,
})

Span type mapping

Mastra Span Type	PostHog Event Type
MODEL_INFERENCE	$ai_generation
MODEL_GENERATION	$ai_span
MODEL_STEP	$ai_span
MODEL_CHUNK	$ai_span
TOOL_CALL	$ai_span
MCP_TOOL_CALL	$ai_span
PROVIDER_TOOL_CALL	$ai_span
PROCESSOR_RUN	$ai_span
AGENT_RUN	$ai_span
WORKFLOW_RUN	$ai_span
All other workflows	$ai_span
GENERIC	$ai_span

Each call to the model provider is a MODEL_INFERENCE span and is exported as one $ai_generation event. The event carries the model, token usage, output, and the tool definitions sent on that call as $ai_tools. Its $ai_input is the conversation that call received: the run's input messages, followed by the output and tool results of each earlier call in the run. A run that calls the model three times sends three $ai_generation events.

The MODEL_GENERATION span wraps those calls and is exported as $ai_span. PostHog only adds up tokens and cost on $ai_generation events. Tokens and cost aren't counted twice. With @mastra/core or @mastra/observability versions that don't record MODEL_INFERENCE spans, MODEL_GENERATION is exported as $ai_generation.

备注

Runs through the deprecated generateLegacy() and streamLegacy() methods don't record MODEL_INFERENCE spans. Their MODEL_GENERATION span is exported as $ai_span. These runs send no $ai_generation events and no token or cost data to PostHog. Use generate() and stream() to keep token and cost data.

Feedback export

Feedback recorded with addFeedback() is exported to PostHog as a native $ai_feedback event. PostHog shows it as User feedback on the linked trace. No extra configuration is needed.

const trace = await mastra.observability.getRecordedTrace({ traceId })
await trace.addFeedback({
  feedbackType: 'thumbs',
  value: 'down',
  comment: 'Wrong answer',
})

Feedback events map to these PostHog properties:

Mastra feedback field	PostHog property
traceId	$ai_trace_id
comment (or value when no comment)	$ai_feedback_text
feedbackId	feedback_id
feedbackType	feedback_type
value	feedback_value
feedbackSource	feedback_source
spanId	span_id
sourceId	source_id
metadata.sessionId	$ai_session_id
metadata (other keys)	custom properties

Feedback without a traceId is dropped because PostHog anchors feedback to a trace through $ai_trace_id. The event's distinct ID resolves from feedbackUserId, then metadata.userId, then defaultDistinctId, then anonymous.