PosthogExporter

将 Tracing 数据发送到 PostHog，用于 AI 可观测性和分析。

构造函数

new PosthogExporter(config: PosthogExporterConfig)

PosthogExporterConfig

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

扩展自 BaseExporterConfig，其中包括：

• logger?: IMastraLogger - Logger 实例
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - 日志级别（默认：INFO）

方法

exportTracingEvent

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

将 tracing 事件导出到 PostHog。

onFeedbackEvent

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

将反馈事件导出到 PostHog。请参阅反馈导出。

flush

async flush(): Promise<void>

在不关闭 Exporter 的情况下，强制将所有已缓冲事件刷新到 PostHog。适用于需要在运行时终止前确保 Span 已导出的 serverless 环境。

shutdown

async shutdown(): Promise<void>

刷新待处理的批量事件，并关闭 PostHog 客户端。

用法

零配置（使用环境变量）

import { PosthogExporter } from '@mastra/posthog'

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

显式配置

import { PosthogExporter } from '@mastra/posthog'

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

Span 类型映射

Mastra Span 类型	PostHog 事件类型
MODEL_GENERATION	$ai_generation
MODEL_STEP	$ai_generation
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
所有其他工作流	$ai_span
GENERIC	$ai_span

反馈导出

通过 addFeedback() 记录的反馈会作为原生 $ai_feedback 事件导出到 PostHog。PostHog 会在关联的 Trace 上将其显示为 User feedback。无需额外配置。

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

反馈事件会映射到以下 PostHog 属性：

Mastra 反馈字段	PostHog 属性
traceId	$ai_trace_id
comment（没有 comment 时使用 value）	$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（其他键）	自定义属性

没有 traceId 的反馈会被丢弃，因为 PostHog 通过 $ai_trace_id 将反馈关联到 Trace。事件的 distinct ID 依次取自 feedbackUserId、metadata.userId、defaultDistinctId，最后使用 anonymous。