@countly/ai-sdk-mastra 0.0.1 → 0.0.2
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.
- package/README.md +120 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# @countly/ai-sdk-mastra
|
|
2
|
+
|
|
3
|
+
> Countly AI observability adapter for [Mastra](https://mastra.ai).
|
|
4
|
+
|
|
5
|
+
Part of the [Countly AI SDK](https://github.com/Countly/countly-ai-sdk) — provider-agnostic LLM observability for every AI stack.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @countly/ai-sdk-mastra
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`@countly/ai-sdk-core` is pulled in automatically.
|
|
14
|
+
|
|
15
|
+
## Peer dependencies
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
@mastra/core >= 1.0.0
|
|
19
|
+
@mastra/observability >= 0.1.0
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
23
|
+
|
|
24
|
+
> **Note**: the exporter must be wrapped in `new Observability({...})` and passed via Mastra's `observability:` field. Passing it directly as `exporters:` on Mastra won't work — no spans reach the exporter.
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import { Mastra } from "@mastra/core/mastra";
|
|
28
|
+
import { Observability } from "@mastra/observability";
|
|
29
|
+
import { CountlyMastraExporter } from "@countly/ai-sdk-mastra";
|
|
30
|
+
|
|
31
|
+
new Mastra({
|
|
32
|
+
observability: new Observability({
|
|
33
|
+
configs: {
|
|
34
|
+
default: {
|
|
35
|
+
serviceName: "my-ai-app",
|
|
36
|
+
exporters: [
|
|
37
|
+
new CountlyMastraExporter({
|
|
38
|
+
appKey: "YOUR_APP_KEY",
|
|
39
|
+
url: "https://your-countly-server.com",
|
|
40
|
+
requestContextDeviceIdKey: "countlyDeviceId",
|
|
41
|
+
}),
|
|
42
|
+
],
|
|
43
|
+
},
|
|
44
|
+
},
|
|
45
|
+
}),
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
In your request handler:
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { RequestContext } from "@mastra/core/request-context";
|
|
53
|
+
|
|
54
|
+
app.post("/chat", async (req, res) => {
|
|
55
|
+
const ctx = new RequestContext();
|
|
56
|
+
ctx.set("countlyDeviceId", req.user.id);
|
|
57
|
+
await mastra.getAgent("intent").stream(messages, { requestContext: ctx });
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## How the user ID reaches the event
|
|
62
|
+
|
|
63
|
+
The bridge is Mastra's runtime, not our SDK. We read a public field Mastra puts on every exported span:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
Your handler Mastra runtime @countly/ai-sdk-mastra
|
|
67
|
+
───────────── ────────────── ──────────────────────
|
|
68
|
+
ctx = new RequestContext()
|
|
69
|
+
ctx.set("countlyDeviceId", id)
|
|
70
|
+
run scope carries ctx
|
|
71
|
+
agent.stream(msg, { ↓
|
|
72
|
+
requestContext: ctx spans created during run
|
|
73
|
+
}) (AGENT_RUN, MODEL_GEN, TOOL_CALL)
|
|
74
|
+
↓
|
|
75
|
+
ExportedSpan.requestContext = {
|
|
76
|
+
countlyDeviceId: id adapter reads
|
|
77
|
+
} span.requestContext
|
|
78
|
+
↓
|
|
79
|
+
event.deviceId = id
|
|
80
|
+
POST /i?device_id=id
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
- Rename the key via `requestContextDeviceIdKey` (e.g. `"myUserId"`)
|
|
84
|
+
- Set to `null` to disable — falls back to `getDeviceId()` / `deviceId` / process UUID
|
|
85
|
+
- No Mastra version requirement beyond `>=1.0` — stable v1 observability surface
|
|
86
|
+
|
|
87
|
+
## What's captured
|
|
88
|
+
|
|
89
|
+
- Per-event tracing via `exportTracingEvent` (`span_started`, `span_updated`, `span_ended`)
|
|
90
|
+
- Automatic trace completion when the root span ends (no `parentSpanId`)
|
|
91
|
+
- Token usage, cost, and latency aggregated across all spans of a trace
|
|
92
|
+
- Tool calls within agent workflows (`function_call` and `mcp_tool_call` types)
|
|
93
|
+
- Error reporting for failed traces
|
|
94
|
+
- Per-user aggregation across agent runs
|
|
95
|
+
|
|
96
|
+
## Configuration
|
|
97
|
+
|
|
98
|
+
All adapters accept the same `CountlyAIConfig` object:
|
|
99
|
+
|
|
100
|
+
| Field | Default | Description |
|
|
101
|
+
|-------|---------|-------------|
|
|
102
|
+
| `appKey` | *required* | Countly app key |
|
|
103
|
+
| `url` | *required* | Countly server URL |
|
|
104
|
+
| `requestContextDeviceIdKey` | `"countlyDeviceId"` | Key to read from Mastra's `requestContext`. Set to `null` to disable. |
|
|
105
|
+
| `observabilityLevel` | `0` | `0` = metrics only, `1` = + tool calls, `2` = + text previews |
|
|
106
|
+
| `tags` | `[]` | Labels for cost attribution and filtering |
|
|
107
|
+
| `environment` | `"production"` | Environment tag |
|
|
108
|
+
| `costModel` | — | Custom pricing overrides |
|
|
109
|
+
| `flushInterval` | `10000` | Buffer flush interval in ms |
|
|
110
|
+
| `maxBatchSize` | `20` | Max events before auto-flush |
|
|
111
|
+
| `debug` | `false` | Log transport errors |
|
|
112
|
+
| `disabled` | `false` | Disable all telemetry |
|
|
113
|
+
|
|
114
|
+
## Full documentation
|
|
115
|
+
|
|
116
|
+
See the [Countly AI SDK repository](https://github.com/Countly/countly-ai-sdk) for the unified data model, observability levels, cost calculation, privacy controls, and Countly plugin integration (Drill, Funnels, Cohorts, APM, Crash Analytics).
|
|
117
|
+
|
|
118
|
+
## License
|
|
119
|
+
|
|
120
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@countly/ai-sdk-mastra",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.2",
|
|
4
4
|
"description": "Countly AI observability adapter for Mastra",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"access": "public"
|
|
17
17
|
},
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"@countly/ai-sdk-core": "0.0.
|
|
19
|
+
"@countly/ai-sdk-core": "0.0.2"
|
|
20
20
|
},
|
|
21
21
|
"peerDependencies": {
|
|
22
22
|
"@mastra/core": ">=1.0.0",
|