@mastra/posthog 1.3.6 → 1.3.7-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +13 -166
  2. package/dist/tracing.d.ts.map +1 -1
  3. package/package.json +8 -9
  4. package/CHANGELOG.md +0 -1488
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @mastra/posthog
2
2
 
3
- PostHog AI Observability exporter for Mastra applications.
3
+ Export Mastra traces to PostHog AI observability as structured events, with project credentials, host configuration, and serverless flushing.
4
4
 
5
5
  ## Installation
6
6
 
@@ -10,186 +10,33 @@ npm install @mastra/posthog
10
10
 
11
11
  ## Usage
12
12
 
13
- ### Zero-Config Setup
14
-
15
- The exporter automatically reads credentials from environment variables:
16
-
17
- ```bash
18
- # Required
19
- POSTHOG_API_KEY=phc_...
20
-
21
- # Optional
22
- POSTHOG_HOST=https://us.i.posthog.com # or eu.i.posthog.com
23
- ```
13
+ Set `POSTHOG_API_KEY` before creating the exporter.
24
14
 
25
15
  ```typescript
16
+ import { Mastra } from '@mastra/core/mastra';
17
+ import { Observability } from '@mastra/observability';
26
18
  import { PosthogExporter } from '@mastra/posthog';
27
19
 
28
- const mastra = new Mastra({
29
- ...,
30
- observability: {
20
+ export const mastra = new Mastra({
21
+ observability: new Observability({
31
22
  configs: {
32
23
  posthog: {
33
24
  serviceName: 'my-service',
34
25
  exporters: [new PosthogExporter()],
35
26
  },
36
27
  },
37
- },
28
+ }),
38
29
  });
39
30
  ```
40
31
 
41
- ### Explicit Configuration
42
-
43
- You can also pass credentials directly:
44
-
45
- ```typescript
46
- import { PosthogExporter } from '@mastra/posthog';
47
-
48
- const mastra = new Mastra({
49
- ...,
50
- observability: {
51
- configs: {
52
- posthog: {
53
- serviceName: 'my-service',
54
- exporters: [
55
- new PosthogExporter({
56
- apiKey: 'phc_...',
57
- host: 'https://us.i.posthog.com', // optional, defaults to US region
58
- }),
59
- ],
60
- },
61
- },
62
- },
63
- });
64
- ```
65
-
66
- ## Features
67
-
68
- ### AI Tracing
69
-
70
- - **Event-based architecture**: Captures LLM calls and operations as PostHog events
71
- - **LLM analytics**: Automatic tracking of token usage, latency, and costs
72
- - **Streaming support**: Handles streaming LLM responses with MODEL_CHUNK events
73
- - **Privacy mode**: Optional exclusion of input/output data for sensitive applications
74
- - **Serverless optimized**: Auto-configures batching for serverless environments
75
-
76
- ### Supported Event Types
77
-
78
- - `$ai_generation`: LLM model calls (MODEL_GENERATION, MODEL_STEP)
79
- - `$ai_span`: Operations like tool calls, workflows, and streaming chunks
80
- - Hierarchical traces with parent-child relationships via `$ai_parent_id`
81
- - Session grouping with `$ai_session_id`
82
-
83
- ## Configuration
84
-
85
- ### Basic Configuration
86
-
87
- ```typescript
88
- new PosthogExporter({
89
- apiKey: process.env.POSTHOG_API_KEY,
90
- });
91
- ```
92
-
93
- ### Advanced Configuration
94
-
95
- ```typescript
96
- new PosthogExporter({
97
- // Required
98
- apiKey: process.env.POSTHOG_API_KEY,
99
-
100
- // Optional: Region/Host
101
- host: 'https://eu.i.posthog.com', // EU region
102
- // or
103
- host: 'https://your-instance.com', // Self-hosted
104
-
105
- // Optional: Batching (defaults: flushAt=20, flushInterval=10000)
106
- flushAt: 20, // Batch size before auto-flush
107
- flushInterval: 10000, // Flush interval in milliseconds
32
+ ## Documentation
108
33
 
109
- // Optional: Serverless mode (auto-configures smaller batches)
110
- serverless: true, // Sets flushAt=10, flushInterval=2000
34
+ - [PostHog](https://mastra.ai/integrations/observability/posthog)
111
35
 
112
- // Optional: User identification
113
- defaultDistinctId: 'anonymous', // Fallback if no userId in metadata
36
+ ## Changelog
114
37
 
115
- // Optional: Privacy
116
- enablePrivacyMode: false, // Set to true to exclude input/output from LLM events
117
- });
118
- ```
119
-
120
- ### Serverless Environments
121
-
122
- When deploying to serverless environments (Lambda, Vercel Functions, etc.), enable serverless mode:
123
-
124
- ```typescript
125
- new PosthogExporter({
126
- apiKey: process.env.POSTHOG_API_KEY,
127
- serverless: true, // Auto-configures for serverless
128
- });
129
- ```
130
-
131
- **Important**: Always call `await mastra.shutdown()` before your serverless function exits to flush remaining events.
132
-
133
- ### Privacy Mode
134
-
135
- To exclude sensitive input/output data while still tracking token usage and latency:
136
-
137
- ```typescript
138
- new PosthogExporter({
139
- apiKey: process.env.POSTHOG_API_KEY,
140
- enablePrivacyMode: true, // Excludes $ai_input and $ai_output_choices
141
- });
142
- ```
143
-
144
- Note: Privacy mode only applies to `$ai_generation` events. Span events (tool calls, etc.) still include input/output state.
145
-
146
- ## Metadata
147
-
148
- Include metadata in your Mastra spans to enrich PostHog events:
149
-
150
- ```typescript
151
- // User identification
152
- {
153
- metadata: {
154
- userId: 'user-123', // → distinctId in PostHog
155
- sessionId: 'session-abc', // → $ai_session_id for grouping
156
-
157
- // Custom properties (passed through to PostHog)
158
- environment: 'production',
159
- version: '1.0.0',
160
- }
161
- }
162
- ```
163
-
164
- ## Cost Tracking
165
-
166
- PostHog automatically calculates costs from:
167
-
168
- - Model name + token counts (uses OpenRouter pricing data)
169
- - Or you can send pre-calculated costs in span attributes
170
-
171
- ## Viewing Data in PostHog
172
-
173
- 1. Navigate to **Product Analytics** → **Events**
174
- 2. Filter for events starting with `$ai_`
175
- 3. Use the **AI Observability** dashboard (if available in your PostHog plan)
176
- 4. Query events by:
177
- - `$ai_trace_id`: Group all events in a trace
178
- - `$ai_session_id`: Group traces in a session
179
- - `$ai_model`: Filter by model (e.g., "gpt-4o")
180
- - `$ai_provider`: Filter by provider (e.g., "openai")
181
-
182
- ## Environment Variables
183
-
184
- ```bash
185
- # Required
186
- POSTHOG_API_KEY=phc_...
187
-
188
- # Optional
189
- POSTHOG_HOST=https://us.i.posthog.com # or eu.i.posthog.com
190
- ```
38
+ See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/observability/posthog/CHANGELOG.md) for version history and release notes.
191
39
 
192
- ## Links
40
+ ## Support
193
41
 
194
- - [PostHog LLM Analytics Documentation](https://posthog.com/docs/ai-engineering/langchain-integration)
195
- - [Mastra Observability Documentation](https://mastra.ai/docs/observability)
42
+ We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.
package/dist/tracing.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,13 +1,12 @@
1
1
  {
2
2
  "name": "@mastra/posthog",
3
- "version": "1.3.6",
3
+ "version": "1.3.7-alpha.1",
4
4
  "description": "PostHog observability provider for Mastra",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
8
8
  "files": [
9
- "dist",
10
- "CHANGELOG.md"
9
+ "dist"
11
10
  ],
12
11
  "exports": {
13
12
  ".": {
@@ -25,18 +24,18 @@
25
24
  "license": "Apache-2.0",
26
25
  "dependencies": {
27
26
  "posthog-node": "^5.46.1",
28
- "@mastra/observability": "1.17.4"
27
+ "@mastra/observability": "1.17.5-alpha.1"
29
28
  },
30
29
  "devDependencies": {
31
30
  "@types/node": "22.20.1",
32
31
  "eslint": "^10.7.0",
33
32
  "tsdown": "0.22.9",
34
- "typescript": "^6.0.3",
33
+ "typescript": "^7.0.2",
35
34
  "vitest": "4.1.10",
36
- "@internal/types-builder": "0.0.103",
37
- "@internal/lint": "0.0.128",
38
- "@mastra/core": "1.63.1",
39
- "@observability/test-utils": "0.1.0"
35
+ "@internal/types-builder": "0.0.104",
36
+ "@observability/test-utils": "0.1.0",
37
+ "@internal/lint": "0.0.129",
38
+ "@mastra/core": "1.64.0-alpha.7"
40
39
  },
41
40
  "peerDependencies": {
42
41
  "@mastra/core": ">=1.16.0-0 <2.0.0-0"