@mastra/observability 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/model-tracing.d.ts

@@ -8,13 +8,7 @@
  * Hierarchy: MODEL_GENERATION -> MODEL_STEP -> MODEL_CHUNK
  */
 import { SpanType } from '@mastra/core/observability';
-import type { Span, EndSpanOptions, ErrorSpanOptions, TracingContext, UpdateSpanOptions } from '@mastra/core/observability';
-/**
- * Manages MODEL_STEP and MODEL_CHUNK span tracking for streaming Model responses.
- *
- * Should be instantiated once per MODEL_GENERATION span and shared across
- * all streaming steps (including after tool calls).
- */
+import type { Span, EndGenerationOptions, ErrorSpanOptions, TracingContext, UpdateSpanOptions } from '@mastra/core/observability';
 export declare class ModelSpanTracker {
     #private;
     constructor(modelSpan?: Span<SpanType.MODEL_GENERATION>);
@@ -28,9 +22,10 @@ export declare class ModelSpanTracker {
      */
     reportGenerationError(options: ErrorSpanOptions<SpanType.MODEL_GENERATION>): void;
     /**
-     * End the generation span
+     * End the generation span with optional raw usage data.
+     * If usage is provided, it will be converted to UsageStats with cache token details.
      */
-    endGeneration(options?: EndSpanOptions<SpanType.MODEL_GENERATION>): void;
+    endGeneration(options?: EndGenerationOptions): void;
     /**
      * Update the generation span
      */

package/dist/model-tracing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-tracing.d.ts","sourceRoot":"","sources":["../src/model-tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,KAAK,EACV,IAAI,EACJ,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAGpC;;;;;GAKG;AACH,qBAAa,gBAAgB;;gBAQf,SAAS,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAIvD;;;OAGG;IACH,iBAAiB,IAAI,cAAc;IAMnC;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAIjF;;OAEG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAIxE;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IA4O7E;;;;;OAKG;IACH,UAAU,CAAC,CAAC,SAAS;QAAE,WAAW,EAAE,QAAQ,CAAA;KAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC;CAyE9D"}
+{"version":3,"file":"model-tracing.d.ts","sourceRoot":"","sources":["../src/model-tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,KAAK,EACV,IAAI,EACJ,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAuBpC,qBAAa,gBAAgB;;gBAaf,SAAS,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAcvD;;;OAGG;IACH,iBAAiB,IAAI,cAAc;IAMnC;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAIjF;;;OAGG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,IAAI;IAWnD;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IA+V7E;;;;;OAKG;IACH,UAAU,CAAC,CAAC,SAAS;QAAE,WAAW,EAAE,QAAQ,CAAA;KAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC;CAwG9D"}

package/dist/spans/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/spans/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/spans/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,WAAW,EACX,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,QAAQ,EAAiB,MAAM,4BAA4B,CAAC;AA6CrE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS,CAYvF;AAED,8BAAsB,QAAQ,CAAC,KAAK,SAAS,QAAQ,GAAG,GAAG,CAAE,YAAW,IAAI,CAAC,KAAK,CAAC;IACjF,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,SAAS,CAAC,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B,CAAC;IACK,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,CAAC;IAC/B,0EAA0E;IAC1E,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,qBAAqB,EAAE,qBAAqB;IAwB3F,mBAAmB;IACnB,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,IAAI;IAEnD,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI;IAEtD,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI;IAExD,eAAe,CAAC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,qBAAqB;IAK5F,eAAe,CAAC,UAAU,SAAS,QAAQ,EAAE,OAAO,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;IAItG;;;OAGG;IACH,aAAa,IAAI,iBAAiB,GAAG,SAAS;IAS9C,6DAA6D;IAC7D,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,oEAAoE;IACpE,QAAQ,KAAK,OAAO,IAAI,OAAO,CAAC;IAEhC,gEAAgE;IACzD,eAAe,CAAC,oBAAoB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAW1E,qFAAqF;IAC9E,UAAU,CAAC,CAAC,SAAS,QAAQ,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS;IAavE,kDAAkD;IAC3C,UAAU,CAAC,oBAAoB,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC;IAqBtE,IAAI,eAAe,IAAI,MAAM,GAAG,SAAS,CAExC;IAED;;;OAGG;IACG,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAU3D;;;OAGG;IACH,oBAAoB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;CASxC;AASD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,GAAG,EACV,OAAO,GAAE,gBAAqB,EAC9B,KAAK,GAAE,OAAO,CAAC,GAAG,CAAiB,EACnC,MAAM,GAAE,MAAU,GACjB,GAAG,CA6CL"}

package/dist/tracing-options.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Composable Tracing Options Builder
+ */
+import type { TracingOptions } from '@mastra/core/observability';
+/**
+ * A function that updates TracingOptions.
+ */
+export type TracingOptionsUpdater = (options: TracingOptions) => TracingOptions;
+/**
+ * Builds TracingOptions by composing one or more updater functions.
+ *
+ * @example
+ * ```typescript
+ * import { buildTracingOptions } from '@mastra/observability';
+ * import { withLangfusePrompt } from '@mastra/langfuse';
+ *
+ * const prompt = await langfuse.getPrompt('my-prompt');
+ *
+ * const agent = new Agent({
+ *   defaultGenerateOptions: {
+ *     tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+ *   },
+ * });
+ * ```
+ */
+export declare function buildTracingOptions(...updaters: TracingOptionsUpdater[]): TracingOptions;
+//# sourceMappingURL=tracing-options.d.ts.map

package/dist/tracing-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-options.d.ts","sourceRoot":"","sources":["../src/tracing-options.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,cAAc,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,QAAQ,EAAE,qBAAqB,EAAE,GAAG,cAAc,CAExF"}

package/dist/usage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Usage extraction utilities for converting AI SDK usage to Mastra UsageStats
+ */
+import type { UsageStats } from '@mastra/core/observability';
+import type { LanguageModelUsage, ProviderMetadata } from '@mastra/core/stream';
+/**
+ * Extracts and normalizes token usage from AI SDK response, including
+ * provider-specific cache tokens from providerMetadata.
+ *
+ * Handles:
+ * - OpenAI: cachedInputTokens in usage object
+ * - Anthropic: cacheCreationInputTokens, cacheReadInputTokens in providerMetadata.anthropic
+ * - Google/Gemini: cachedContentTokenCount, thoughtsTokenCount in providerMetadata.google.usageMetadata
+ * - OpenRouter: Uses OpenAI-compatible structure (cache tokens in usage)
+ *
+ * @param usage - The LanguageModelV2Usage from AI SDK response
+ * @param providerMetadata - Optional provider-specific metadata
+ * @returns UsageStats with inputDetails and outputDetails
+ */
+export declare function extractUsageMetrics(usage?: LanguageModelUsage, providerMetadata?: ProviderMetadata): UsageStats;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAyC,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACpG,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAoBhF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,UAAU,CA4E/G"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/observability",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "Core observability package for Mastra - includes tracing and scoring features",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
     "vitest": "4.0.12",
     "@internal/types-builder": "0.0.28",
     "@internal/lint": "0.0.53",
-    "@mastra/core": "1.0.0-beta.6"
+    "@mastra/core": "1.0.0-beta.10"
   },
   "dependencies": {
     "zod": "^3.25.76"