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

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @mastra/observability
 
+## 1.0.0-beta.4
+
+### Patch Changes
+
+- Fixed CachedToken tracking in all Observability Exporters. Also fixed TimeToFirstToken in Langfuse, Braintrust, PostHog exporters. Fixed trace formatting in Posthog Exporter. ([#11029](https://github.com/mastra-ai/mastra/pull/11029))
+
+- Updated dependencies [[`edb07e4`](https://github.com/mastra-ai/mastra/commit/edb07e49283e0c28bd094a60e03439bf6ecf0221), [`b7e17d3`](https://github.com/mastra-ai/mastra/commit/b7e17d3f5390bb5a71efc112204413656fcdc18d), [`261473a`](https://github.com/mastra-ai/mastra/commit/261473ac637e633064a22076671e2e02b002214d), [`5d7000f`](https://github.com/mastra-ai/mastra/commit/5d7000f757cd65ea9dc5b05e662fd83dfd44e932), [`4f0331a`](https://github.com/mastra-ai/mastra/commit/4f0331a79bf6eb5ee598a5086e55de4b5a0ada03), [`8a000da`](https://github.com/mastra-ai/mastra/commit/8a000da0c09c679a2312f6b3aa05b2ca78ca7393)]:
+  - @mastra/core@1.0.0-beta.10
+
+## 1.0.0-beta.3
+
+### Patch Changes
+
+- Add time-to-first-token (TTFT) support for Braintrust integration ([#10840](https://github.com/mastra-ai/mastra/pull/10840))
+
+  Adds `time_to_first_token` metric to Braintrust spans, populated from the `completionStartTime` attribute captured when the first streaming chunk arrives.
+
+  ```typescript
+  // time_to_first_token is now automatically sent to Braintrust
+  // as part of span metrics during streaming
+  const result = await agent.stream('Hello');
+  ```
+
+- Add time-to-first-token (TTFT) support for Langfuse integration ([#10781](https://github.com/mastra-ai/mastra/pull/10781))
+
+  Adds `completionStartTime` to model generation spans, which Langfuse uses to calculate TTFT metrics. The timestamp is automatically captured when the first content chunk arrives during streaming.
+
+  ```typescript
+  // completionStartTime is now automatically captured and sent to Langfuse
+  // enabling TTFT metrics in your Langfuse dashboard
+  const result = await agent.stream('Hello');
+  ```
+
+- Consolidated tool-output chunks from nested agents into single tool-result spans ([#10836](https://github.com/mastra-ai/mastra/pull/10836))
+
+- link langfuse prompts and helper functions ([#10738](https://github.com/mastra-ai/mastra/pull/10738))
+
+- Updated dependencies [[`3076c67`](https://github.com/mastra-ai/mastra/commit/3076c6778b18988ae7d5c4c5c466366974b2d63f), [`85d7ee1`](https://github.com/mastra-ai/mastra/commit/85d7ee18ff4e14d625a8a30ec6656bb49804989b), [`c6c1092`](https://github.com/mastra-ai/mastra/commit/c6c1092f8fbf76109303f69e000e96fd1960c4ce), [`81dc110`](https://github.com/mastra-ai/mastra/commit/81dc11008d147cf5bdc8996ead1aa61dbdebb6fc), [`7aedb74`](https://github.com/mastra-ai/mastra/commit/7aedb74883adf66af38e270e4068fd42e7a37036), [`8f02d80`](https://github.com/mastra-ai/mastra/commit/8f02d800777397e4b45d7f1ad041988a8b0c6630), [`d7aad50`](https://github.com/mastra-ai/mastra/commit/d7aad501ce61646b76b4b511e558ac4eea9884d0), [`ce0a73a`](https://github.com/mastra-ai/mastra/commit/ce0a73abeaa75b10ca38f9e40a255a645d50ebfb), [`a02e542`](https://github.com/mastra-ai/mastra/commit/a02e542d23179bad250b044b17ff023caa61739f), [`a372c64`](https://github.com/mastra-ai/mastra/commit/a372c640ad1fd12e8f0613cebdc682fc156b4d95), [`8846867`](https://github.com/mastra-ai/mastra/commit/8846867ffa9a3746767618e314bebac08eb77d87), [`42a42cf`](https://github.com/mastra-ai/mastra/commit/42a42cf3132b9786feecbb8c13c583dce5b0e198), [`ae08bf0`](https://github.com/mastra-ai/mastra/commit/ae08bf0ebc6a4e4da992b711c4a389c32ba84cf4), [`21735a7`](https://github.com/mastra-ai/mastra/commit/21735a7ef306963554a69a89b44f06c3bcd85141), [`1d877b8`](https://github.com/mastra-ai/mastra/commit/1d877b8d7b536a251c1a7a18db7ddcf4f68d6f8b)]:
+  - @mastra/core@1.0.0-beta.7
+
 ## 1.0.0-beta.2
 
 ### Minor Changes

package/dist/index.cjs

@@ -948,6 +948,58 @@ var TestExporter = class extends BaseExporter {
     this.logger.info("TestExporter shutdown");
   }
 };
+
+// src/usage.ts
+function extractUsageMetrics(usage, providerMetadata) {
+  if (!usage) {
+    return {};
+  }
+  const inputDetails = {};
+  const outputDetails = {};
+  let inputTokens = usage.inputTokens;
+  const outputTokens = usage.outputTokens;
+  if (usage.cachedInputTokens) {
+    inputDetails.cacheRead = usage.cachedInputTokens;
+  }
+  if (usage.reasoningTokens) {
+    outputDetails.reasoning = usage.reasoningTokens;
+  }
+  const anthropic = providerMetadata?.anthropic;
+  if (anthropic) {
+    if (anthropic.cacheReadInputTokens) {
+      inputDetails.cacheRead = anthropic.cacheReadInputTokens;
+    }
+    if (anthropic.cacheCreationInputTokens) {
+      inputDetails.cacheWrite = anthropic.cacheCreationInputTokens;
+    }
+    if (anthropic.cacheReadInputTokens || anthropic.cacheCreationInputTokens) {
+      inputDetails.text = usage.inputTokens;
+      inputTokens = (usage.inputTokens ?? 0) + (anthropic.cacheReadInputTokens ?? 0) + (anthropic.cacheCreationInputTokens ?? 0);
+    }
+  }
+  const google = providerMetadata?.google;
+  if (google?.usageMetadata) {
+    if (google.usageMetadata.cachedContentTokenCount) {
+      inputDetails.cacheRead = google.usageMetadata.cachedContentTokenCount;
+    }
+    if (google.usageMetadata.thoughtsTokenCount) {
+      outputDetails.reasoning = google.usageMetadata.thoughtsTokenCount;
+    }
+  }
+  const result = {
+    inputTokens,
+    outputTokens
+  };
+  if (Object.keys(inputDetails).length > 0) {
+    result.inputDetails = inputDetails;
+  }
+  if (Object.keys(outputDetails).length > 0) {
+    result.outputDetails = outputDetails;
+  }
+  return result;
+}
+
+// src/model-tracing.ts
 var ModelSpanTracker = class {
   #modelSpan;
   #currentStepSpan;
@@ -955,9 +1007,23 @@ var ModelSpanTracker = class {
   #accumulator = {};
   #stepIndex = 0;
   #chunkSequence = 0;
+  #completionStartTime;
+  /** Tracks tool output accumulators by toolCallId for consolidating sub-agent streams */
+  #toolOutputAccumulators = /* @__PURE__ */ new Map();
+  /** Tracks toolCallIds that had streaming output (to skip redundant tool-result spans) */
+  #streamedToolCallIds = /* @__PURE__ */ new Set();
   constructor(modelSpan) {
     this.#modelSpan = modelSpan;
   }
+  /**
+   * Capture the completion start time (time to first token) when the first content chunk arrives.
+   */
+  #captureCompletionStartTime() {
+    if (this.#completionStartTime) {
+      return;
+    }
+    this.#completionStartTime = /* @__PURE__ */ new Date();
+  }
   /**
    * Get the tracing context for creating child spans.
    * Returns the current step span if active, otherwise the model span.
@@ -974,10 +1040,16 @@ var ModelSpanTracker = class {
     this.#modelSpan?.error(options);
   }
   /**
-   * 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) {
-    this.#modelSpan?.end(options);
+    const { usage, providerMetadata, ...spanOptions } = options ?? {};
+    if (spanOptions.attributes) {
+      spanOptions.attributes.completionStartTime = this.#completionStartTime;
+      spanOptions.attributes.usage = extractUsageMetrics(usage, providerMetadata);
+    }
+    this.#modelSpan?.end(spanOptions);
   }
   /**
    * Update the generation span
@@ -1007,9 +1079,10 @@ var ModelSpanTracker = class {
   #endStepSpan(payload) {
     if (!this.#currentStepSpan) return;
     const output = payload.output;
-    const { usage, ...otherOutput } = output;
+    const { usage: rawUsage, ...otherOutput } = output;
     const stepResult = payload.stepResult;
     const metadata = payload.metadata;
+    const usage = extractUsageMetrics(rawUsage, metadata?.providerMetadata);
     const cleanMetadata = metadata ? { ...metadata } : void 0;
     if (cleanMetadata?.request) {
       delete cleanMetadata.request;
@@ -1182,6 +1255,77 @@ var ModelSpanTracker = class {
         break;
     }
   }
+  /**
+   * Handle tool-output chunks from sub-agents.
+   * Consolidates streaming text/reasoning deltas into a single span per tool call.
+   */
+  #handleToolOutputChunk(chunk) {
+    if (chunk.type !== "tool-output") return;
+    const payload = chunk.payload;
+    const { output, toolCallId, toolName } = payload;
+    let acc = this.#toolOutputAccumulators.get(toolCallId);
+    if (!acc) {
+      if (!this.#currentStepSpan) {
+        this.#startStepSpan();
+      }
+      acc = {
+        toolName: toolName || "unknown",
+        toolCallId,
+        text: "",
+        reasoning: "",
+        sequenceNumber: this.#chunkSequence++,
+        // Name the span 'tool-result' for consistency (tool-call → tool-result)
+        span: this.#currentStepSpan?.createChildSpan({
+          name: `chunk: 'tool-result'`,
+          type: observability.SpanType.MODEL_CHUNK,
+          attributes: {
+            chunkType: "tool-result",
+            sequenceNumber: this.#chunkSequence - 1
+          }
+        })
+      };
+      this.#toolOutputAccumulators.set(toolCallId, acc);
+    }
+    if (output && typeof output === "object" && "type" in output) {
+      const innerType = output.type;
+      switch (innerType) {
+        case "text-delta":
+          if (output.payload?.text) {
+            acc.text += output.payload.text;
+          }
+          break;
+        case "reasoning-delta":
+          if (output.payload?.text) {
+            acc.reasoning += output.payload.text;
+          }
+          break;
+        case "finish":
+        case "workflow-finish":
+          this.#endToolOutputSpan(toolCallId);
+          break;
+      }
+    }
+  }
+  /**
+   * End a tool output span and clean up the accumulator
+   */
+  #endToolOutputSpan(toolCallId) {
+    const acc = this.#toolOutputAccumulators.get(toolCallId);
+    if (!acc) return;
+    const output = {
+      toolCallId: acc.toolCallId,
+      toolName: acc.toolName
+    };
+    if (acc.text) {
+      output.text = acc.text;
+    }
+    if (acc.reasoning) {
+      output.reasoning = acc.reasoning;
+    }
+    acc.span?.end({ output });
+    this.#toolOutputAccumulators.delete(toolCallId);
+    this.#streamedToolCallIds.add(toolCallId);
+  }
   /**
    * Wraps a stream with model tracing transform to track MODEL_STEP and MODEL_CHUNK spans.
    *
@@ -1192,6 +1336,13 @@ var ModelSpanTracker = class {
     return stream.pipeThrough(
       new web.TransformStream({
         transform: (chunk, controller) => {
+          switch (chunk.type) {
+            case "text-delta":
+            case "tool-call-delta":
+            case "reasoning-delta":
+              this.#captureCompletionStartTime();
+              break;
+          }
           controller.enqueue(chunk);
           switch (chunk.type) {
             case "text-start":
@@ -1225,6 +1376,19 @@ var ModelSpanTracker = class {
             case "start":
             case "finish":
               break;
+            case "tool-output":
+              this.#handleToolOutputChunk(chunk);
+              break;
+            case "tool-result": {
+              const toolCallId = chunk.payload?.toolCallId;
+              if (toolCallId && this.#streamedToolCallIds.has(toolCallId)) {
+                this.#streamedToolCallIds.delete(toolCallId);
+                break;
+              }
+              const { args, ...cleanPayload } = chunk.payload || {};
+              this.#createEventSpan(chunk.type, cleanPayload);
+              break;
+            }
             // Default: auto-create event span for all other chunk types
             default: {
               let outputPayload = chunk.payload;
@@ -1436,6 +1600,9 @@ function deepClean(value, options = {}, _seen = /* @__PURE__ */ new WeakSet(), _
     return "[Circular]";
   }
   _seen.add(value);
+  if (value instanceof Date) {
+    return value;
+  }
   if (Array.isArray(value)) {
     return value.map((item) => deepClean(item, options, _seen, _depth + 1));
   }
@@ -2324,6 +2491,11 @@ var Observability = class extends base.MastraBase {
   }
 };
 
+// src/tracing-options.ts
+function buildTracingOptions(...updaters) {
+  return updaters.reduce((opts, updater) => updater(opts), {});
+}
+
 exports.BaseExporter = BaseExporter;
 exports.BaseObservabilityInstance = BaseObservabilityInstance;
 exports.BaseSpan = BaseSpan;
@@ -2338,6 +2510,7 @@ exports.Observability = Observability;
 exports.SamplingStrategyType = SamplingStrategyType;
 exports.SensitiveDataFilter = SensitiveDataFilter;
 exports.TestExporter = TestExporter;
+exports.buildTracingOptions = buildTracingOptions;
 exports.deepClean = deepClean;
 exports.getExternalParentId = getExternalParentId;
 exports.observabilityConfigValueSchema = observabilityConfigValueSchema;