@countly/ai-sdk-mastra

Countly AI observability adapter for Mastra.

Part of the Countly AI SDK — provider-agnostic LLM observability for every AI stack.

Install

npm install @countly/ai-sdk-mastra

@countly/ai-sdk-core is pulled in automatically.

Peer dependencies

@mastra/core >= 1.0.0
@mastra/observability >= 0.1.0

Quick Start

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.

import { Mastra } from "@mastra/core/mastra";
import { Observability } from "@mastra/observability";
import { CountlyMastraExporter } from "@countly/ai-sdk-mastra";

new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: "my-ai-app",
        exporters: [
          new CountlyMastraExporter({
            appKey: "YOUR_APP_KEY",
            url: "https://your-countly-server.com",
            requestContextDeviceIdKey: "countlyDeviceId",
          }),
        ],
      },
    },
  }),
});

In your request handler:

import { RequestContext } from "@mastra/core/request-context";

app.post("/chat", async (req, res) => {
  const ctx = new RequestContext();
  ctx.set("countlyDeviceId", req.user.id);
  await mastra.getAgent("intent").stream(messages, { requestContext: ctx });
});

How the user ID reaches the event

The bridge is Mastra's runtime, not our SDK. We read a public field Mastra puts on every exported span:

Your handler                     Mastra runtime                  @countly/ai-sdk-mastra
─────────────                    ──────────────                  ──────────────────────
ctx = new RequestContext()
ctx.set("countlyDeviceId", id)
                                 run scope carries ctx
agent.stream(msg, {              ↓
  requestContext: ctx            spans created during run
})                               (AGENT_RUN, MODEL_GEN, TOOL_CALL)
                                 ↓
                                 ExportedSpan.requestContext = {
                                   countlyDeviceId: id              adapter reads
                                 }                                  span.requestContext
                                                                    ↓
                                                                    event.deviceId = id
                                                                    POST /i?device_id=id

• Rename the key via requestContextDeviceIdKey (e.g. "myUserId")
• Set to null to disable — falls back to getDeviceId() / deviceId / process UUID
• No Mastra version requirement beyond >=1.0 — stable v1 observability surface

What's captured

• Per-event tracing via exportTracingEvent (span_started, span_updated, span_ended)
• Automatic trace completion when the root span ends (no parentSpanId)
• Token usage, cost, and latency aggregated across all spans of a trace
• Tool calls within agent workflows (function_call and mcp_tool_call types)
• Error reporting for failed traces
• Per-user aggregation across agent runs

Configuration

All adapters accept the same CountlyAIConfig object:

| Field | Default | Description | |-------|---------|-------------| | appKey | required | Countly app key | | url | required | Countly server URL | | requestContextDeviceIdKey | "countlyDeviceId" | Key to read from Mastra's requestContext. Set to null to disable. | | observabilityLevel | 0 | 0 = metrics only, 1 = + tool calls, 2 = + text previews | | tags | [] | Labels for cost attribution and filtering | | environment | "production" | Environment tag | | costModel | — | Custom pricing overrides | | flushInterval | 10000 | Buffer flush interval in ms | | maxBatchSize | 20 | Max events before auto-flush | | debug | false | Log transport errors | | disabled | false | Disable all telemetry |

Full documentation

See the Countly AI SDK repository for the unified data model, observability levels, cost calculation, privacy controls, and Countly plugin integration (Drill, Funnels, Cohorts, APM, Crash Analytics).

License

MIT