PosthogExporter

Envoie les données de Tracing à PostHog pour l’observabilité et l’analyse de l’IA.

Constructeur

new PosthogExporter(config: PosthogExporterConfig)

PosthogExporterConfig

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

Étend BaseExporterConfig, qui comprend :

• logger?: IMastraLogger - Instance du logger
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Niveau de log (valeur par défaut : INFO)

Méthodes

exportTracingEvent

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

Exporte un événement de tracing vers PostHog.

onFeedbackEvent

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

Exporte un événement de retour vers PostHog. Consultez la section Exportation des retours.

flush

async flush(): Promise<void>

Force l’envoi vers PostHog de tous les événements mis en mémoire tampon sans arrêter l’exportateur. Cette méthode est utile dans les environnements serverless où vous devez vous assurer que les spans sont exportés avant l’arrêt du runtime.

shutdown

async shutdown(): Promise<void>

Envoie les lots d’événements en attente et arrête le client PostHog.

Utilisation

Sans configuration (avec des variables d’environnement)

import { PosthogExporter } from '@mastra/posthog'

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

Configuration explicite

import { PosthogExporter } from '@mastra/posthog'

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

Correspondance des types de spans

Type de span Mastra	Type d’événement 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
Tous les autres Workflows	$ai_span
GENERIC	$ai_span

Exportation des retours

Les retours enregistrés avec addFeedback() sont exportés vers PostHog comme événements natifs $ai_feedback. PostHog les affiche sous l’intitulé User feedback dans la trace associée. Aucune configuration supplémentaire n’est nécessaire.

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

Les événements de retour correspondent aux propriétés PostHog suivantes :

Champ de retour Mastra	Propriété PostHog
traceId	$ai_trace_id
comment (ou value en l’absence de commentaire)	$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 (autres clés)	propriétés personnalisées

Les retours dépourvus de traceId sont abandonnés, car PostHog les associe à une trace au moyen de $ai_trace_id. L’ID distinct de l’événement est résolu à partir de feedbackUserId, puis de metadata.userId, de defaultDistinctId et enfin de anonymous.