@mastra/observability 1.12.0 → 1.13.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/observability
 
+## 1.13.0-alpha.0
+
+### Minor Changes
+
+- Roll up token usage from internal MODEL_GENERATION spans onto the closest exported ancestor span. When `tracingPolicy.internal` filters a model call out of exported traces, its tokens used to disappear from both the trace UI and metrics. Now: ([#16434](https://github.com/mastra-ai/mastra/pull/16434))
+  - The visible ancestor (e.g. `PROCESSOR_RUN`, `AGENT_RUN`) gets an `internalUsage` attribute summing the tokens consumed by its hidden descendants — so a Mastra-owned processor that runs an internal agent (moderation, PII detector, structured output, etc.) shows its aggregate cost on the visible `PROCESSOR_RUN` span.
+  - Token / cost metrics still emit, but are attributed via labels to the visible ancestor instead of the hidden agent.
+
+  No action required — the rollup applies automatically whenever an internal `MODEL_GENERATION` ends inside a non-internal ancestor.
+
+### Patch Changes
+
+- Updated dependencies [[`8cdb86c`](https://github.com/mastra-ai/mastra/commit/8cdb86ceed1137bc2768e147dce85a0692b9fb26), [`eda90c5`](https://github.com/mastra-ai/mastra/commit/eda90c5bfd7de11805ecc9f4552716c895fbaf78), [`afc004f`](https://github.com/mastra-ai/mastra/commit/afc004f5cc7e30697809e7021820b9f5881e6719), [`408be73`](https://github.com/mastra-ai/mastra/commit/408be73449dfab92b51eab8c6623b6c443debc25)]:
+  - @mastra/core@1.36.0-alpha.1
+
 ## 1.12.0
 
 ### Minor Changes

package/dist/features.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAqC,CAAC"}
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAA8D,CAAC"}

package/dist/index.cjs

@@ -19029,6 +19029,7 @@ var PricingRegistry = class _PricingRegistry {
   constructor(pricingModels) {
     this.pricingModels = pricingModels;
   }
+  pricingModels;
   static globalRegistry = null;
   static fromText(pricingModelText) {
     return new _PricingRegistry(parsePricingModelText(pricingModelText));
@@ -19432,6 +19433,9 @@ function emitTokenMetrics(span, metrics) {
   }
   emitUsageMetrics(attrs, attrs.usage, metrics);
 }
+function emitTokenMetricsForUsage(usage, provider, model, metrics) {
+  emitUsageMetrics({ provider, model }, usage, metrics);
+}
 function emitAutoExtractedMetrics(span, metrics) {
   emitDurationMetrics(span, metrics);
   emitTokenMetrics(span, metrics);
@@ -19593,6 +19597,46 @@ function extractUsageMetrics(usage, providerMetadata) {
 function sumDefinedValues(obj, keys) {
   return keys.reduce((sum, key) => sum + (obj[key] ?? 0), 0);
 }
+function addOptional(a, b) {
+  if (a === void 0 && b === void 0) return void 0;
+  return (a ?? 0) + (b ?? 0);
+}
+function mergeInputDetails(a, b) {
+  if (!a) return b ? { ...b } : void 0;
+  if (!b) return { ...a };
+  return {
+    text: addOptional(a.text, b.text),
+    cacheRead: addOptional(a.cacheRead, b.cacheRead),
+    cacheWrite: addOptional(a.cacheWrite, b.cacheWrite),
+    audio: addOptional(a.audio, b.audio),
+    image: addOptional(a.image, b.image)
+  };
+}
+function mergeOutputDetails(a, b) {
+  if (!a) return b ? { ...b } : void 0;
+  if (!b) return { ...a };
+  return {
+    text: addOptional(a.text, b.text),
+    reasoning: addOptional(a.reasoning, b.reasoning),
+    audio: addOptional(a.audio, b.audio),
+    image: addOptional(a.image, b.image)
+  };
+}
+function addUsageStats(a, b) {
+  if (!a) {
+    return {
+      ...b,
+      inputDetails: b.inputDetails ? { ...b.inputDetails } : void 0,
+      outputDetails: b.outputDetails ? { ...b.outputDetails } : void 0
+    };
+  }
+  return {
+    inputTokens: addOptional(a.inputTokens, b.inputTokens),
+    outputTokens: addOptional(a.outputTokens, b.outputTokens),
+    inputDetails: mergeInputDetails(a.inputDetails, b.inputDetails),
+    outputDetails: mergeOutputDetails(a.outputDetails, b.outputDetails)
+  };
+}
 
 // src/model-tracing.ts
 function supportsModelInference() {
@@ -21122,7 +21166,7 @@ var BaseObservabilityInstance = class extends base.MastraBase {
    * This ensures all spans emit events regardless of implementation
    */
   wireSpanLifecycle(span) {
-    if (!this.config.includeInternalSpans && span.isInternal) {
+    if (!this.config.includeInternalSpans && span.isInternal && span.type !== observability.SpanType.MODEL_GENERATION) {
       return;
     }
     const originalEnd = span.end.bind(span);
@@ -21132,7 +21176,11 @@ var BaseObservabilityInstance = class extends base.MastraBase {
         this.logger.warn(`End event is not available on event spans`);
         return;
       }
+      const rollupTarget = this.captureModelUsageRollup(span, options);
       originalEnd(options);
+      if (rollupTarget) {
+        this.applyUsageRollup(rollupTarget);
+      }
       this.emitSpanEnded(span);
     };
     span.update = (options) => {
@@ -21306,6 +21354,70 @@ var BaseObservabilityInstance = class extends base.MastraBase {
       this.emitTracingEvent(event);
     }
   }
+  /**
+   * When an internal MODEL_GENERATION span ends, capture the rollup payload
+   * (usage, provider, model, target ancestor) needed to attribute its cost
+   * to the closest exported ancestor span. Returns undefined when no rollup
+   * applies — non-MODEL_GENERATION spans, spans that will be exported, or
+   * spans whose usage isn't available at end time.
+   */
+  captureModelUsageRollup(span, endOptions) {
+    if (span.type !== observability.SpanType.MODEL_GENERATION) return void 0;
+    if (!span.isInternal || this.config.includeInternalSpans) return void 0;
+    const endAttrs = endOptions?.attributes ?? void 0;
+    const liveAttrs = span.attributes;
+    const usage = endAttrs?.usage ?? liveAttrs?.usage;
+    if (!usage) return void 0;
+    const ancestor = this.findExportedAncestor(span);
+    if (!ancestor) return void 0;
+    const provider = endAttrs?.provider ?? liveAttrs?.provider;
+    const model = endAttrs?.responseModel ?? endAttrs?.model ?? liveAttrs?.responseModel ?? liveAttrs?.model;
+    return { ancestor, usage, provider, model };
+  }
+  /**
+   * Accumulate usage onto the ancestor's `internalUsage` attribute (for trace
+   * UI visibility) and emit auto-extracted token metrics now, using the
+   * ancestor's metrics context so cost / token labels point at the visible
+   * span instead of the hidden agent that incurred them.
+   */
+  applyUsageRollup(target) {
+    const { ancestor, usage, provider, model } = target;
+    const attrs = ancestor.attributes;
+    attrs.internalUsage = addUsageStats(attrs.internalUsage, usage);
+    try {
+      emitTokenMetricsForUsage(usage, provider, model, this.getMetricsContext(ancestor));
+    } catch (err) {
+      this.logger.error("[Observability] Usage rollup metric emission error:", err);
+    }
+  }
+  /**
+   * Walk up the parent chain to find the closest ancestor that will actually
+   * reach exporters. Skips both internal-filtered ancestors and ancestors
+   * whose type matches `excludeSpanTypes`, so the rollup target is one whose
+   * mutated `internalUsage` attribute is visible in exported traces.
+   *
+   * Note: this does not preemptively run `spanFilter` — that filter can be
+   * async and have side effects, so the rare case of a `spanFilter`-dropped
+   * ancestor falls through.
+   */
+  findExportedAncestor(span) {
+    let ancestor = span.parent;
+    while (ancestor && this.isFilteredFromExport(ancestor)) {
+      ancestor = ancestor.parent;
+    }
+    return ancestor;
+  }
+  /**
+   * Returns true when a span would be dropped by `getSpanForExport` for a
+   * reason cheap to check up-front (internal-span filtering or
+   * `excludeSpanTypes`). Used by `findExportedAncestor` to skip rollup
+   * targets that would silently lose their `internalUsage` attribute.
+   */
+  isFilteredFromExport(span) {
+    if (span.isInternal && !this.config.includeInternalSpans) return true;
+    if (this.config.excludeSpanTypes?.includes(span.type)) return true;
+    return false;
+  }
   /**
    * Emit a tracing event through the bus.
    *
@@ -22256,7 +22368,7 @@ var Observability = class extends base.MastraBase {
 };
 
 // src/features.ts
-var observabilityFeatures = /* @__PURE__ */ new Set(["model-inference-span"]);
+var observabilityFeatures = /* @__PURE__ */ new Set(["model-inference-span", "internal-usage-rollup"]);
 
 // src/tracing-options.ts
 function buildTracingOptions(...updaters) {