Exporter PostHog

PostHog est une plateforme d’analyse dotée de fonctionnalités d’observabilité de l’IA pour surveiller les applications LLM. L’exporter PostHog envoie vos traces à PostHog sous forme d’événements structurés afin de fournir des informations sur l’utilisation des jetons, les coûts, la latence et les flux de conversation.

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

Prérequis

1. Compte PostHog : inscrivez-vous sur posthog.com
2. Clé API du projet : récupérez-la dans PostHog sous Settings → Project API Key
3. Variables d’environnement : définissez vos identifiants

.env

# Required
POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx

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

Configuration automatique

Une fois les variables d’environnement définies, utilisez l’exporter sans 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()],
      },
    },
  }),
})

Configuration explicite

Vous pouvez également transmettre les identifiants directement ; ils prévalent sur les variables d’environnement :

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,
          }),
        ],
      },
    },
  }),
})

Options de configuration

Configuration complète

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
})

Mode serverless

Regroupement optimisé pour les environnements serverless :

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

Mode de confidentialité

Excluez les données d’entrée et de sortie des événements de génération tout en conservant les métriques de jetons :

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

Analyse par groupe

Pour associer des événements à un groupe PostHog, ajoutez un objet $groups à tracingOptions.metadata. L’exporter transmet ces valeurs dans le champ de premier niveau groups de l’appel de capture PostHog, ce qui permet de segmenter des analyses telles que le coût du LLM par groupe.

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

Pages connexes

• Présentation du tracing
• Documentation PostHog