PosthogExporter

AI の Observability と分析のために Tracing データを PostHog へ送信します。

コンストラクター

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 が確実にエクスポートされるようにする必要があるサーバーレス環境で役立ちます。

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
その他すべての Workflow	$ai_span
GENERIC	$ai_span

フィードバックのエクスポート

addFeedback() で記録されたフィードバックは、ネイティブの $ai_feedback イベントとして PostHog へエクスポートされます。PostHog では、リンクされた Trace 上に ユーザーフィードバック として表示されます。追加設定は不要です。

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（ない場合は 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（その他のキー）	カスタムプロパティ

PostHog は $ai_trace_id を介してフィードバックを Trace に紐付けるため、traceId のないフィードバックは破棄されます。イベントの distinct ID は、feedbackUserId、metadata.userId、defaultDistinctId、anonymous の順で決定されます。