@mastra/observability 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from './spans/index.js';
 export * from './exporters/index.js';
 export * from './span_processors/index.js';
 export * from './model-tracing.js';
+export * from './tracing-options.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,cAAc,UAAU,CAAC;AAGzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,cAAc,UAAU,CAAC;AAGzB,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -35,18 +35,38 @@ var observabilityInstanceConfigSchema = z.object({
   serviceName: z.string().min(1, "Service name is required"),
   sampling: samplingStrategySchema.optional(),
   exporters: z.array(z.any()).optional(),
+  bridge: z.any().optional(),
   spanOutputProcessors: z.array(z.any()).optional(),
   includeInternalSpans: z.boolean().optional(),
   requestContextKeys: z.array(z.string()).optional()
-});
+}).refine(
+  (data) => {
+    const hasExporters = data.exporters && data.exporters.length > 0;
+    const hasBridge = !!data.bridge;
+    return hasExporters || hasBridge;
+  },
+  {
+    message: "At least one exporter or a bridge is required"
+  }
+);
 var observabilityConfigValueSchema = z.object({
   serviceName: z.string().min(1, "Service name is required"),
   sampling: samplingStrategySchema.optional(),
   exporters: z.array(z.any()).optional(),
+  bridge: z.any().optional(),
   spanOutputProcessors: z.array(z.any()).optional(),
   includeInternalSpans: z.boolean().optional(),
   requestContextKeys: z.array(z.string()).optional()
-});
+}).refine(
+  (data) => {
+    const hasExporters = data.exporters && data.exporters.length > 0;
+    const hasBridge = !!data.bridge;
+    return hasExporters || hasBridge;
+  },
+  {
+    message: "At least one exporter or a bridge is required"
+  }
+);
 var observabilityRegistryConfigSchema = z.object({
   default: z.object({
     enabled: z.boolean().optional()
@@ -73,6 +93,18 @@ var observabilityRegistryConfigSchema = z.object({
   {
     message: 'A "configSelector" function is required when multiple configs are specified to determine which config to use.'
   }
+).refine(
+  (data) => {
+    if (data.configSelector) {
+      const isDefaultEnabled = data.default?.enabled === true;
+      const hasConfigs = data.configs && typeof data.configs === "object" && !Array.isArray(data.configs) ? Object.keys(data.configs).length > 0 : false;
+      return isDefaultEnabled || hasConfigs;
+    }
+    return true;
+  },
+  {
+    message: 'A "configSelector" requires at least one config or default observability to be configured.'
+  }
 );
 var BaseExporter = class {
   /** Mastra logger instance */
@@ -893,6 +925,27 @@ var DefaultExporter = class extends BaseExporter {
     this.logger.info("DefaultExporter shutdown complete");
   }
 };
+
+// src/exporters/test.ts
+var TestExporter = class extends BaseExporter {
+  name = "tracing-test-exporter";
+  #events = [];
+  constructor(config = {}) {
+    super(config);
+  }
+  async _exportTracingEvent(event) {
+    this.#events.push(event);
+  }
+  clearEvents() {
+    this.#events = [];
+  }
+  get events() {
+    return this.#events;
+  }
+  async shutdown() {
+    this.logger.info("TestExporter shutdown");
+  }
+};
 var ModelSpanTracker = class {
   #modelSpan;
   #currentStepSpan;
@@ -900,9 +953,30 @@ var ModelSpanTracker = class {
   #accumulator = {};
   #stepIndex = 0;
   #chunkSequence = 0;
+  /** Tracks whether completionStartTime has been captured for this generation */
+  #completionStartTimeCaptured = false;
+  /** 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.
+   * This is used by observability providers like Langfuse to calculate TTFT metrics.
+   */
+  #captureCompletionStartTime() {
+    if (this.#completionStartTimeCaptured || !this.#modelSpan) {
+      return;
+    }
+    this.#completionStartTimeCaptured = true;
+    this.#modelSpan.update({
+      attributes: {
+        completionStartTime: /* @__PURE__ */ new Date()
+      }
+    });
+  }
   /**
    * Get the tracing context for creating child spans.
    * Returns the current step span if active, otherwise the model span.
@@ -1127,6 +1201,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: 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.
    *
@@ -1134,9 +1279,14 @@ var ModelSpanTracker = class {
    * create MODEL_STEP and MODEL_CHUNK spans for each semantic unit in the stream.
    */
   wrapStream(stream) {
+    let captureCompletionStartTime = false;
     return stream.pipeThrough(
       new TransformStream({
         transform: (chunk, controller) => {
+          if (!captureCompletionStartTime) {
+            captureCompletionStartTime = true;
+            this.#captureCompletionStartTime();
+          }
           controller.enqueue(chunk);
           switch (chunk.type) {
             case "text-start":
@@ -1170,6 +1320,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;
@@ -1224,6 +1387,16 @@ function isSpanInternal(spanType, flags) {
       return false;
   }
 }
+function getExternalParentId(options) {
+  if (!options.parent) {
+    return void 0;
+  }
+  if (options.parent.isInternal) {
+    return options.parent.getParentSpanId(false);
+  } else {
+    return options.parent.id;
+  }
+}
 var BaseSpan = class {
   name;
   type;
@@ -1238,6 +1411,7 @@ var BaseSpan = class {
   output;
   errorInfo;
   metadata;
+  tags;
   traceState;
   /** Parent span ID (for root spans that are children of external spans) */
   parentSpanId;
@@ -1252,6 +1426,7 @@ var BaseSpan = class {
     this.isEvent = options.isEvent ?? false;
     this.isInternal = isSpanInternal(this.type, options.tracingPolicy?.internal);
     this.traceState = options.traceState;
+    this.tags = !options.parent && options.tags?.length ? options.tags : void 0;
     if (this.isEvent) {
       this.output = deepClean(options.output);
     } else {
@@ -1314,12 +1489,36 @@ var BaseSpan = class {
       errorInfo: this.errorInfo,
       isEvent: this.isEvent,
       isRootSpan: this.isRootSpan,
-      parentSpanId: this.getParentSpanId(includeInternalSpans)
+      parentSpanId: this.getParentSpanId(includeInternalSpans),
+      // Tags are only included for root spans
+      ...this.isRootSpan && this.tags?.length ? { tags: this.tags } : {}
     };
   }
   get externalTraceId() {
     return this.isValid ? this.traceId : void 0;
   }
+  /**
+   * Execute an async function within this span's tracing context.
+   * Delegates to the bridge if available.
+   */
+  async executeInContext(fn) {
+    const bridge = this.observabilityInstance.getBridge();
+    if (bridge?.executeInContext) {
+      return bridge.executeInContext(this.id, fn);
+    }
+    return fn();
+  }
+  /**
+   * Execute a synchronous function within this span's tracing context.
+   * Delegates to the bridge if available.
+   */
+  executeInContextSync(fn) {
+    const bridge = this.observabilityInstance.getBridge();
+    if (bridge?.executeInContextSync) {
+      return bridge.executeInContextSync(this.id, fn);
+    }
+    return fn();
+  }
 };
 var DEFAULT_KEYS_TO_STRIP = /* @__PURE__ */ new Set([
   "logger",
@@ -1366,27 +1565,30 @@ var DefaultSpan = class extends BaseSpan {
   traceId;
   constructor(options, observabilityInstance) {
     super(options, observabilityInstance);
-    this.id = generateSpanId();
+    const bridge = observabilityInstance.getBridge();
+    if (bridge && !this.isInternal) {
+      const bridgeIds = bridge.createSpan(options);
+      if (bridgeIds) {
+        this.id = bridgeIds.spanId;
+        this.traceId = bridgeIds.traceId;
+        this.parentSpanId = bridgeIds.parentSpanId;
+        return;
+      }
+    }
     if (options.parent) {
       this.traceId = options.parent.traceId;
-    } else if (options.traceId) {
-      if (isValidTraceId(options.traceId)) {
-        this.traceId = options.traceId;
-      } else {
-        console.error(
-          `[Mastra Tracing] Invalid traceId: must be 1-32 hexadecimal characters, got "${options.traceId}". Generating new trace ID.`
-        );
-        this.traceId = generateTraceId();
-      }
-    } else {
-      this.traceId = generateTraceId();
+      this.parentSpanId = options.parent.id;
+      this.id = generateSpanId();
+      return;
     }
-    if (!options.parent && options.parentSpanId) {
+    this.traceId = getOrCreateTraceId(options);
+    this.id = generateSpanId();
+    if (options.parentSpanId) {
       if (isValidSpanId(options.parentSpanId)) {
         this.parentSpanId = options.parentSpanId;
       } else {
         console.error(
-          `[Mastra Tracing] Invalid parentSpanId: must be 1-16 hexadecimal characters, got "${options.parentSpanId}". Ignoring parent span ID.`
+          `[Mastra Tracing] Invalid parentSpanId: must be 1-16 hexadecimal characters, got "${options.parentSpanId}". Ignoring.`
         );
       }
     }
@@ -1491,6 +1693,18 @@ function isValidTraceId(traceId) {
 function isValidSpanId(spanId) {
   return /^[0-9a-f]{1,16}$/i.test(spanId);
 }
+function getOrCreateTraceId(options) {
+  if (options.traceId) {
+    if (isValidTraceId(options.traceId)) {
+      return options.traceId;
+    } else {
+      console.error(
+        `[Mastra Tracing] Invalid traceId: must be 1-32 hexadecimal characters, got "${options.traceId}". Generating new trace ID.`
+      );
+    }
+  }
+  return generateTraceId();
+}
 
 // src/spans/no-op.ts
 var NoOpSpan = class extends BaseSpan {
@@ -1523,13 +1737,17 @@ var BaseObservabilityInstance = class extends MastraBase {
       sampling: config.sampling ?? { type: "always" /* ALWAYS */ },
       exporters: config.exporters ?? [],
       spanOutputProcessors: config.spanOutputProcessors ?? [],
+      bridge: config.bridge ?? void 0,
       includeInternalSpans: config.includeInternalSpans ?? false,
       requestContextKeys: config.requestContextKeys ?? []
     };
+    if (this.config.bridge?.init) {
+      this.config.bridge.init({ config: this.config });
+    }
   }
   /**
    * Override setLogger to add Observability specific initialization log
-   * and propagate logger to exporters
+   * and propagate logger to exporters and bridge
    */
   __setLogger(logger) {
     super.__setLogger(logger);
@@ -1538,8 +1756,11 @@ var BaseObservabilityInstance = class extends MastraBase {
         exporter.__setLogger(logger);
       }
     });
+    if (this.config.bridge?.__setLogger) {
+      this.config.bridge.__setLogger(logger);
+    }
     this.logger.debug(
-      `[Observability] Initialized [service=${this.config.serviceName}] [instance=${this.config.name}] [sampling=${this.config.sampling.type}]`
+      `[Observability] Initialized [service=${this.config.serviceName}] [instance=${this.config.name}] [sampling=${this.config.sampling?.type}] [bridge=${!!this.config.bridge}]`
     );
   }
   // ============================================================================
@@ -1568,11 +1789,15 @@ var BaseObservabilityInstance = class extends MastraBase {
     } else {
       traceState = this.computeTraceState(tracingOptions);
     }
-    const enrichedMetadata = this.extractMetadataFromRequestContext(requestContext, metadata, traceState);
+    const tracingMetadata = !options.parent ? tracingOptions?.metadata : void 0;
+    const mergedMetadata = metadata || tracingMetadata ? { ...metadata, ...tracingMetadata } : void 0;
+    const enrichedMetadata = this.extractMetadataFromRequestContext(requestContext, mergedMetadata, traceState);
+    const tags = !options.parent ? tracingOptions?.tags : void 0;
     const span = this.createSpan({
       ...rest,
       metadata: enrichedMetadata,
-      traceState
+      traceState,
+      tags
     });
     if (span.isEvent) {
       this.emitSpanEnded(span);
@@ -1606,6 +1831,12 @@ var BaseObservabilityInstance = class extends MastraBase {
   getSpanOutputProcessors() {
     return [...this.spanOutputProcessors];
   }
+  /**
+   * Get the bridge instance if configured
+   */
+  getBridge() {
+    return this.config.bridge;
+  }
   /**
    * Get the logger instance (for exporters and other components)
    */
@@ -1650,7 +1881,9 @@ var BaseObservabilityInstance = class extends MastraBase {
    */
   shouldSample(options) {
     const { sampling } = this.config;
-    switch (sampling.type) {
+    switch (sampling?.type) {
+      case void 0:
+        return true;
       case "always" /* ALWAYS */:
         return true;
       case "never" /* NEVER */:
@@ -1782,17 +2015,21 @@ var BaseObservabilityInstance = class extends MastraBase {
     }
   }
   /**
-   * Export tracing event through all exporters (realtime mode)
+   * Export tracing event through all exporters and bridge (realtime mode)
    */
   async exportTracingEvent(event) {
-    const exportPromises = this.exporters.map(async (exporter) => {
+    const targets = [
+      ...this.exporters
+    ];
+    if (this.config.bridge) {
+      targets.push(this.config.bridge);
+    }
+    const exportPromises = targets.map(async (target) => {
       try {
-        if (exporter.exportTracingEvent) {
-          await exporter.exportTracingEvent(event);
-          this.logger.debug(`[Observability] Event exported [exporter=${exporter.name}] [type=${event.type}]`);
-        }
+        await target.exportTracingEvent(event);
+        this.logger.debug(`[Observability] Event exported [target=${target.name}] [type=${event.type}]`);
       } catch (error) {
-        this.logger.error(`[Observability] Export error [exporter=${exporter.name}]`, error);
+        this.logger.error(`[Observability] Export error [target=${target.name}]`, error);
       }
     });
     await Promise.allSettled(exportPromises);
@@ -1816,6 +2053,9 @@ var BaseObservabilityInstance = class extends MastraBase {
       ...this.exporters.map((e) => e.shutdown()),
       ...this.spanOutputProcessors.map((p) => p.shutdown())
     ];
+    if (this.config.bridge) {
+      shutdownPromises.push(this.config.bridge.shutdown());
+    }
     await Promise.allSettled(shutdownPromises);
     this.logger.info(`[Observability] Shutdown completed [name=${this.name}]`);
   }
@@ -1962,9 +2202,16 @@ var SensitiveDataFilter = class {
   /**
    * Recursively filter objects/arrays for sensitive keys.
    * Handles circular references by replacing with a marker.
+   * Also attempts to parse and redact JSON strings.
    */
   deepFilter(obj, seen = /* @__PURE__ */ new WeakSet()) {
     if (obj === null || typeof obj !== "object") {
+      if (typeof obj === "string") {
+        const trimmed = obj.trim();
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+          return this.redactJsonString(obj);
+        }
+      }
       return obj;
     }
     if (seen.has(obj)) {
@@ -2017,6 +2264,22 @@ var SensitiveDataFilter = class {
       return normalizedKey === sensitiveField;
     });
   }
+  /**
+   * Attempt to parse a string as JSON and redact sensitive fields within it.
+   * If parsing fails or no sensitive data is found, returns the original string.
+   */
+  redactJsonString(str) {
+    try {
+      const parsed = JSON.parse(str);
+      if (parsed && typeof parsed === "object") {
+        const filtered = this.deepFilter(parsed, /* @__PURE__ */ new WeakSet());
+        return JSON.stringify(filtered);
+      }
+      return str;
+    } catch {
+      return str;
+    }
+  }
   /**
    * Redact a sensitive value.
    * - Full style: replaces with a fixed token.
@@ -2169,6 +2432,11 @@ var Observability = class extends MastraBase {
   }
 };
 
-export { BaseExporter, BaseObservabilityInstance, BaseSpan, CloudExporter, ConsoleExporter, DefaultExporter, DefaultObservabilityInstance, DefaultSpan, ModelSpanTracker, NoOpSpan, Observability, SamplingStrategyType, SensitiveDataFilter, deepClean, observabilityConfigValueSchema, observabilityInstanceConfigSchema, observabilityRegistryConfigSchema, samplingStrategySchema };
+// src/tracing-options.ts
+function buildTracingOptions(...updaters) {
+  return updaters.reduce((opts, updater) => updater(opts), {});
+}
+
+export { BaseExporter, BaseObservabilityInstance, BaseSpan, CloudExporter, ConsoleExporter, DefaultExporter, DefaultObservabilityInstance, DefaultSpan, ModelSpanTracker, NoOpSpan, Observability, SamplingStrategyType, SensitiveDataFilter, TestExporter, buildTracingOptions, deepClean, getExternalParentId, observabilityConfigValueSchema, observabilityInstanceConfigSchema, observabilityRegistryConfigSchema, samplingStrategySchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map