@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/docs-observability-tracing-exporters-posthog.md

@@ -0,0 +1,148 @@
+# 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
+
+**npm**:
+
+```bash
+npm install @mastra/posthog@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/posthog@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/posthog@latest
+```
+
+**Bun**:
+
+```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)
+- [PostHog Documentation](https://posthog.com/docs)