# PostHog Exporter

[PostHog](https://posthog.com/) is an analytics platform with AI observability features for monitoring LLM applications. The PostHog exporter sends your traces to PostHog as structured events, providing insights into token usage, costs, latency, and conversation flows.

## Installation

```bash
npm install @mastra/posthog@latest
```

```bash
pnpm add @mastra/posthog@latest
```

```bash
yarn add @mastra/posthog@latest
```

```bash
bun add @mastra/posthog@latest
```

## Configuration

### Prerequisites

1. **PostHog Account**: Sign up at [posthog.com](https://posthog.com/)
2. **Project API Key**: Get your project API key from PostHog Settings → Project API Key
3. **Environment Variables**: Set your credentials

```bash
# Required
POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxx

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

### Zero-Config Setup

With environment variables set, use the exporter with no configuration:

```typescript
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()],
      },
    },
  }),
});
```

### Explicit Configuration

You can also pass credentials directly (takes precedence over environment variables):

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

## Configuration Options

### Complete Configuration

```typescript
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
});
```

### Serverless Mode

Optimized batching for serverless environments:

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

### Privacy Mode

Exclude input/output data from generation events while preserving token metrics:

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

## Related

- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview/llms.txt)
- [PostHog Documentation](https://posthog.com/docs)