@mastra/observability 1.0.0-beta.9 → 1.1.0-alpha.0

package/dist/index.cjs

@@ -5,8 +5,12 @@ var error = require('@mastra/core/error');
 var logger = require('@mastra/core/logger');
 var observability = require('@mastra/core/observability');
 var utils = require('@mastra/core/utils');
+var promises = require('fs/promises');
+var path = require('path');
+var url = require('url');
 var web = require('stream/web');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -3839,7 +3843,7 @@ ZodNaN.create = (params) => {
     ...processCreateParams(params)
   });
 };
-var BRAND = Symbol("zod_brand");
+var BRAND = /* @__PURE__ */ Symbol("zod_brand");
 var ZodBranded = class extends ZodType {
   _parse(input) {
     const { ctx } = this._processInputParams(input);
@@ -4076,6 +4080,12 @@ var samplingStrategySchema = external_exports.discriminatedUnion("type", [
     sampler: external_exports.function().args(external_exports.any().optional()).returns(external_exports.boolean())
   })
 ]);
+var serializationOptionsSchema = external_exports.object({
+  maxStringLength: external_exports.number().int().positive().optional(),
+  maxDepth: external_exports.number().int().positive().optional(),
+  maxArrayLength: external_exports.number().int().positive().optional(),
+  maxObjectKeys: external_exports.number().int().positive().optional()
+}).optional();
 var observabilityInstanceConfigSchema = external_exports.object({
   name: external_exports.string().min(1, "Name is required"),
   serviceName: external_exports.string().min(1, "Service name is required"),
@@ -4084,7 +4094,8 @@ var observabilityInstanceConfigSchema = external_exports.object({
   bridge: external_exports.any().optional(),
   spanOutputProcessors: external_exports.array(external_exports.any()).optional(),
   includeInternalSpans: external_exports.boolean().optional(),
-  requestContextKeys: external_exports.array(external_exports.string()).optional()
+  requestContextKeys: external_exports.array(external_exports.string()).optional(),
+  serializationOptions: serializationOptionsSchema
 }).refine(
   (data) => {
     const hasExporters = data.exporters && data.exporters.length > 0;
@@ -4102,7 +4113,8 @@ var observabilityConfigValueSchema = external_exports.object({
   bridge: external_exports.any().optional(),
   spanOutputProcessors: external_exports.array(external_exports.any()).optional(),
   includeInternalSpans: external_exports.boolean().optional(),
-  requestContextKeys: external_exports.array(external_exports.string()).optional()
+  requestContextKeys: external_exports.array(external_exports.string()).optional(),
+  serializationOptions: serializationOptionsSchema
 }).refine(
   (data) => {
     const hasExporters = data.exporters && data.exporters.length > 0;
@@ -4155,12 +4167,19 @@ var observabilityRegistryConfigSchema = external_exports.object({
 var BaseExporter = class {
   /** Mastra logger instance */
   logger;
+  /** Base configuration (accessible by subclasses) */
+  baseConfig;
   /** Whether this exporter is disabled */
-  isDisabled = false;
+  #disabled = false;
+  /** Public getter for disabled state */
+  get isDisabled() {
+    return this.#disabled;
+  }
   /**
    * Initialize the base exporter with logger
    */
   constructor(config = {}) {
+    this.baseConfig = config;
     const logLevel = this.resolveLogLevel(config.logLevel);
     this.logger = config.logger ?? new logger.ConsoleLogger({ level: logLevel, name: this.constructor.name });
   }
@@ -4195,20 +4214,62 @@ var BaseExporter = class {
    * @param reason - Reason why the exporter is disabled
    */
   setDisabled(reason) {
-    this.isDisabled = true;
+    this.#disabled = true;
     this.logger.warn(`${this.name} disabled: ${reason}`);
   }
+  /**
+   * Apply the customSpanFormatter if configured.
+   * This is called automatically by exportTracingEvent before _exportTracingEvent.
+   *
+   * Supports both synchronous and asynchronous formatters. If the formatter
+   * returns a Promise, it will be awaited.
+   *
+   * @param event - The incoming tracing event
+   * @returns The (possibly modified) event to process
+   */
+  async applySpanFormatter(event) {
+    if (this.baseConfig.customSpanFormatter) {
+      try {
+        const formattedSpan = await this.baseConfig.customSpanFormatter(event.exportedSpan);
+        return {
+          ...event,
+          exportedSpan: formattedSpan
+        };
+      } catch (error) {
+        this.logger.error(`${this.name}: Error in customSpanFormatter`, {
+          error,
+          spanId: event.exportedSpan.id,
+          traceId: event.exportedSpan.traceId
+        });
+      }
+    }
+    return event;
+  }
   /**
    * Export a tracing event
    *
-   * This method checks if the exporter is disabled before calling _exportEvent.
-   * Subclasses should implement _exportEvent instead of overriding this method.
+   * This method checks if the exporter is disabled, applies the customSpanFormatter,
+   * then calls _exportTracingEvent.
+   * Subclasses should implement _exportTracingEvent instead of overriding this method.
    */
   async exportTracingEvent(event) {
     if (this.isDisabled) {
       return;
     }
-    await this._exportTracingEvent(event);
+    const processedEvent = await this.applySpanFormatter(event);
+    await this._exportTracingEvent(processedEvent);
+  }
+  /**
+   * Force flush any buffered/queued spans without shutting down the exporter.
+   *
+   * This is useful in serverless environments where you need to ensure spans
+   * are exported before the runtime instance is terminated, while keeping
+   * the exporter active for future requests.
+   *
+   * Default implementation is a no-op. Override to add flush logic.
+   */
+  async flush() {
+    this.logger.debug(`${this.name} flush called (no-op in base class)`);
   }
   /**
    * Shutdown the exporter and clean up resources
@@ -4219,811 +4280,2609 @@ var BaseExporter = class {
     this.logger.info(`${this.name} shutdown complete`);
   }
 };
-var CloudExporter = class extends BaseExporter {
-  name = "mastra-cloud-observability-exporter";
-  config;
-  buffer;
-  flushTimer = null;
-  constructor(config = {}) {
-    super(config);
-    const accessToken = config.accessToken ?? process.env.MASTRA_CLOUD_ACCESS_TOKEN;
-    if (!accessToken) {
-      this.setDisabled(
-        "MASTRA_CLOUD_ACCESS_TOKEN environment variable not set.\n\u{1F680} Sign up at https://cloud.mastra.ai to see your AI traces online and obtain your access token."
-      );
-    }
-    const endpoint = config.endpoint ?? process.env.MASTRA_CLOUD_TRACES_ENDPOINT ?? "https://api.mastra.ai/ai/spans/publish";
-    this.config = {
-      logger: this.logger,
-      logLevel: config.logLevel ?? logger.LogLevel.INFO,
-      maxBatchSize: config.maxBatchSize ?? 1e3,
-      maxBatchWaitMs: config.maxBatchWaitMs ?? 5e3,
-      maxRetries: config.maxRetries ?? 3,
-      accessToken: accessToken || "",
-      endpoint
-    };
-    this.buffer = {
-      spans: [],
-      totalSize: 0
-    };
+var TraceData = class {
+  /** The vendor-specific root/trace object */
+  #rootSpan;
+  /** The span ID of the root span */
+  #rootSpanId;
+  /** Whether a span with isRootSpan=true has been successfully processed */
+  #rootSpanProcessed;
+  /** Maps eventId to vendor-specific event objects */
+  #events;
+  /** Maps spanId to vendor-specific span objects */
+  #spans;
+  /** Maps spanId to parentSpanId, representing the span hierarchy */
+  #tree;
+  /** Set of span IDs that have started but not yet ended */
+  #activeSpanIds;
+  /** Maps spanId to vendor-specific metadata */
+  #metadata;
+  /** Arbitrary key-value storage for per-trace data */
+  #extraData;
+  /** Events waiting for the root span to be processed */
+  #waitingForRoot;
+  /** Events waiting for specific parent spans, keyed by parentSpanId */
+  #waitingForParent;
+  /** When this trace data was created, used for cap enforcement */
+  createdAt;
+  constructor() {
+    this.#events = /* @__PURE__ */ new Map();
+    this.#spans = /* @__PURE__ */ new Map();
+    this.#activeSpanIds = /* @__PURE__ */ new Set();
+    this.#tree = /* @__PURE__ */ new Map();
+    this.#metadata = /* @__PURE__ */ new Map();
+    this.#extraData = /* @__PURE__ */ new Map();
+    this.#rootSpanProcessed = false;
+    this.#waitingForRoot = [];
+    this.#waitingForParent = /* @__PURE__ */ new Map();
+    this.createdAt = /* @__PURE__ */ new Date();
   }
-  async _exportTracingEvent(event) {
-    if (event.type !== observability.TracingEventType.SPAN_ENDED) {
-      return;
-    }
-    this.addToBuffer(event);
-    if (this.shouldFlush()) {
-      this.flush().catch((error) => {
-        this.logger.error("Batch flush failed", {
-          error: error instanceof Error ? error.message : String(error)
-        });
-      });
-    } else if (this.buffer.totalSize === 1) {
-      this.scheduleFlush();
-    }
+  /**
+   * Check if this trace has a root span registered.
+   * @returns True if addRoot() has been called
+   */
+  hasRoot() {
+    return !!this.#rootSpanId;
   }
-  addToBuffer(event) {
-    if (this.buffer.totalSize === 0) {
-      this.buffer.firstEventTime = /* @__PURE__ */ new Date();
-    }
-    const spanRecord = this.formatSpan(event.exportedSpan);
-    this.buffer.spans.push(spanRecord);
-    this.buffer.totalSize++;
+  /**
+   * Register the root span for this trace.
+   * @param args.rootId - The span ID of the root span
+   * @param args.rootData - The vendor-specific root object
+   */
+  addRoot(args) {
+    this.#rootSpanId = args.rootId;
+    this.#rootSpan = args.rootData;
+    this.#rootSpanProcessed = true;
   }
-  formatSpan(span) {
-    const spanRecord = {
-      traceId: span.traceId,
-      spanId: span.id,
-      parentSpanId: span.parentSpanId ?? null,
-      name: span.name,
-      spanType: span.type,
-      attributes: span.attributes ?? null,
-      metadata: span.metadata ?? null,
-      startedAt: span.startTime,
-      endedAt: span.endTime ?? null,
-      input: span.input ?? null,
-      output: span.output ?? null,
-      error: span.errorInfo,
-      isEvent: span.isEvent,
-      createdAt: /* @__PURE__ */ new Date(),
-      updatedAt: null
-    };
-    return spanRecord;
+  /**
+   * Get the vendor-specific root object.
+   * @returns The root object, or undefined if not yet set
+   */
+  getRoot() {
+    return this.#rootSpan;
   }
-  shouldFlush() {
-    if (this.buffer.totalSize >= this.config.maxBatchSize) {
-      return true;
-    }
-    if (this.buffer.firstEventTime && this.buffer.totalSize > 0) {
-      const elapsed = Date.now() - this.buffer.firstEventTime.getTime();
-      if (elapsed >= this.config.maxBatchWaitMs) {
-        return true;
-      }
-    }
-    return false;
+  /**
+   * Check if a span with isRootSpan=true has been successfully processed.
+   * Set via addRoot() or markRootSpanProcessed().
+   * @returns True if the root span has been processed
+   */
+  isRootProcessed() {
+    return this.#rootSpanProcessed;
   }
-  scheduleFlush() {
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-    }
-    this.flushTimer = setTimeout(() => {
-      this.flush().catch((error$1) => {
-        const mastraError = new error.MastraError(
-          {
-            id: `CLOUD_EXPORTER_FAILED_TO_SCHEDULE_FLUSH`,
-            domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
-            category: error.ErrorCategory.USER
-          },
-          error$1
-        );
-        this.logger.trackException(mastraError);
-        this.logger.error("Scheduled flush failed", mastraError);
-      });
-    }, this.config.maxBatchWaitMs);
+  /**
+   * Mark that the root span has been processed.
+   * Used by exporters with skipBuildRootTask=true where root goes through _buildSpan
+   * instead of _buildRoot.
+   */
+  markRootSpanProcessed() {
+    this.#rootSpanProcessed = true;
   }
-  async flush() {
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
-    }
-    if (this.buffer.totalSize === 0) {
-      return;
-    }
-    const startTime = Date.now();
-    const spansCopy = [...this.buffer.spans];
-    const flushReason = this.buffer.totalSize >= this.config.maxBatchSize ? "size" : "time";
-    this.resetBuffer();
-    try {
-      await this.batchUpload(spansCopy);
-      const elapsed = Date.now() - startTime;
-      this.logger.debug("Batch flushed successfully", {
-        batchSize: spansCopy.length,
-        flushReason,
-        durationMs: elapsed
-      });
-    } catch (error$1) {
-      const mastraError = new error.MastraError(
-        {
-          id: `CLOUD_EXPORTER_FAILED_TO_BATCH_UPLOAD`,
-          domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
-          category: error.ErrorCategory.USER,
-          details: {
-            droppedBatchSize: spansCopy.length
-          }
-        },
-        error$1
-      );
-      this.logger.trackException(mastraError);
-      this.logger.error("Batch upload failed after all retries, dropping batch", mastraError);
-    }
+  /**
+   * Store an arbitrary value in per-trace storage.
+   * @param key - Storage key
+   * @param value - Value to store
+   */
+  setExtraValue(key, value) {
+    this.#extraData.set(key, value);
   }
   /**
-   * Uploads spans to cloud API using fetchWithRetry for all retry logic
+   * Check if a key exists in per-trace storage.
+   * @param key - Storage key
+   * @returns True if the key exists
    */
-  async batchUpload(spans) {
-    const headers = {
-      Authorization: `Bearer ${this.config.accessToken}`,
-      "Content-Type": "application/json"
-    };
-    const options = {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ spans })
-    };
-    await utils.fetchWithRetry(this.config.endpoint, options, this.config.maxRetries);
+  hasExtraValue(key) {
+    return this.#extraData.has(key);
   }
-  resetBuffer() {
-    this.buffer.spans = [];
-    this.buffer.firstEventTime = void 0;
-    this.buffer.totalSize = 0;
+  /**
+   * Get a value from per-trace storage.
+   * @param key - Storage key
+   * @returns The stored value, or undefined if not found
+   */
+  getExtraValue(key) {
+    return this.#extraData.get(key);
   }
-  async shutdown() {
-    if (this.isDisabled) {
-      return;
+  // ============================================================================
+  // Early Queue Methods
+  // ============================================================================
+  /**
+   * Add an event to the waiting queue.
+   * @param args.event - The tracing event to queue
+   * @param args.waitingFor - 'root' or a specific parentSpanId
+   * @param args.attempts - Optional: preserve attempts count when re-queuing
+   * @param args.queuedAt - Optional: preserve original queue time when re-queuing
+   */
+  addToWaitingQueue(args) {
+    const queuedEvent = {
+      event: args.event,
+      waitingFor: args.waitingFor,
+      attempts: args.attempts ?? 0,
+      queuedAt: args.queuedAt ?? /* @__PURE__ */ new Date()
+    };
+    if (args.waitingFor === "root") {
+      this.#waitingForRoot.push(queuedEvent);
+    } else {
+      const queue = this.#waitingForParent.get(args.waitingFor) ?? [];
+      queue.push(queuedEvent);
+      this.#waitingForParent.set(args.waitingFor, queue);
     }
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
+  }
+  /**
+   * Get all events waiting for the root span.
+   * Returns a copy of the internal array.
+   */
+  getEventsWaitingForRoot() {
+    return [...this.#waitingForRoot];
+  }
+  /**
+   * Get all events waiting for a specific parent span.
+   * Returns a copy of the internal array.
+   */
+  getEventsWaitingFor(args) {
+    return [...this.#waitingForParent.get(args.spanId) ?? []];
+  }
+  /**
+   * Clear the waiting-for-root queue.
+   */
+  clearWaitingForRoot() {
+    this.#waitingForRoot = [];
+  }
+  /**
+   * Clear the waiting queue for a specific parent span.
+   */
+  clearWaitingFor(args) {
+    this.#waitingForParent.delete(args.spanId);
+  }
+  /**
+   * Get total count of events in all waiting queues.
+   */
+  waitingQueueSize() {
+    let count = this.#waitingForRoot.length;
+    for (const queue of this.#waitingForParent.values()) {
+      count += queue.length;
     }
-    if (this.buffer.totalSize > 0) {
-      this.logger.info("Flushing remaining events on shutdown", {
-        remainingEvents: this.buffer.totalSize
-      });
-      try {
-        await this.flush();
-      } catch (error$1) {
-        const mastraError = new error.MastraError(
-          {
-            id: `CLOUD_EXPORTER_FAILED_TO_FLUSH_REMAINING_EVENTS_DURING_SHUTDOWN`,
-            domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
-            category: error.ErrorCategory.USER,
-            details: {
-              remainingEvents: this.buffer.totalSize
-            }
-          },
-          error$1
-        );
-        this.logger.trackException(mastraError);
-        this.logger.error("Failed to flush remaining events during shutdown", mastraError);
-      }
+    return count;
+  }
+  /**
+   * Get all queued events across all waiting queues.
+   * Used for cleanup and logging orphaned events.
+   * @returns Array of all queued events
+   */
+  getAllQueuedEvents() {
+    const all = [...this.#waitingForRoot];
+    for (const queue of this.#waitingForParent.values()) {
+      all.push(...queue);
     }
-    this.logger.info("CloudExporter shutdown complete");
+    return all;
   }
-};
-var ConsoleExporter = class extends BaseExporter {
-  name = "tracing-console-exporter";
-  constructor(config = {}) {
-    super(config);
+  // ============================================================================
+  // Span Tree Methods
+  // ============================================================================
+  /**
+   * Record the parent-child relationship for a span.
+   * @param args.spanId - The child span ID
+   * @param args.parentSpanId - The parent span ID, or undefined for root spans
+   */
+  addBranch(args) {
+    this.#tree.set(args.spanId, args.parentSpanId);
   }
-  async _exportTracingEvent(event) {
-    const span = event.exportedSpan;
-    const formatAttributes = (attributes) => {
-      try {
-        return JSON.stringify(attributes, null, 2);
-      } catch (error) {
-        const errMsg = error instanceof Error ? error.message : "Unknown formatting error";
-        return `[Unable to serialize attributes: ${errMsg}]`;
-      }
-    };
-    const formatDuration = (startTime, endTime) => {
-      if (!endTime) return "N/A";
-      const duration = endTime.getTime() - startTime.getTime();
-      return `${duration}ms`;
-    };
-    switch (event.type) {
-      case observability.TracingEventType.SPAN_STARTED:
-        this.logger.info(`\u{1F680} SPAN_STARTED`);
-        this.logger.info(`   Type: ${span.type}`);
-        this.logger.info(`   Name: ${span.name}`);
-        this.logger.info(`   ID: ${span.id}`);
-        this.logger.info(`   Trace ID: ${span.traceId}`);
-        if (span.input !== void 0) {
-          this.logger.info(`   Input: ${formatAttributes(span.input)}`);
-        }
-        this.logger.info(`   Attributes: ${formatAttributes(span.attributes)}`);
-        this.logger.info("\u2500".repeat(80));
-        break;
-      case observability.TracingEventType.SPAN_ENDED:
-        const duration = formatDuration(span.startTime, span.endTime);
-        this.logger.info(`\u2705 SPAN_ENDED`);
+  /**
+   * Get the parent span ID for a given span.
+   * @param args.spanId - The span ID to look up
+   * @returns The parent span ID, or undefined if root or not found
+   */
+  getParentId(args) {
+    return this.#tree.get(args.spanId);
+  }
+  // ============================================================================
+  // Span Management Methods
+  // ============================================================================
+  /**
+   * Register a span and mark it as active.
+   * @param args.spanId - The span ID
+   * @param args.spanData - The vendor-specific span object
+   */
+  addSpan(args) {
+    this.#spans.set(args.spanId, args.spanData);
+    this.#activeSpanIds.add(args.spanId);
+  }
+  /**
+   * Check if a span exists (regardless of active state).
+   * @param args.spanId - The span ID to check
+   * @returns True if the span exists
+   */
+  hasSpan(args) {
+    return this.#spans.has(args.spanId);
+  }
+  /**
+   * Get a span by ID.
+   * @param args.spanId - The span ID to look up
+   * @returns The vendor-specific span object, or undefined if not found
+   */
+  getSpan(args) {
+    return this.#spans.get(args.spanId);
+  }
+  /**
+   * Mark a span as ended (no longer active).
+   * @param args.spanId - The span ID to mark as ended
+   */
+  endSpan(args) {
+    this.#activeSpanIds.delete(args.spanId);
+  }
+  /**
+   * Check if a span is currently active (started but not ended).
+   * @param args.spanId - The span ID to check
+   * @returns True if the span is active
+   */
+  isActiveSpan(args) {
+    return this.#activeSpanIds.has(args.spanId);
+  }
+  /**
+   * Get the count of currently active spans.
+   * @returns Number of active spans
+   */
+  activeSpanCount() {
+    return this.#activeSpanIds.size;
+  }
+  /**
+   * Get all active span IDs.
+   * @returns Array of active span IDs
+   */
+  get activeSpanIds() {
+    return [...this.#activeSpanIds];
+  }
+  // ============================================================================
+  // Event Management Methods
+  // ============================================================================
+  /**
+   * Register an event.
+   * @param args.eventId - The event ID
+   * @param args.eventData - The vendor-specific event object
+   */
+  addEvent(args) {
+    this.#events.set(args.eventId, args.eventData);
+  }
+  // ============================================================================
+  // Metadata Methods
+  // ============================================================================
+  /**
+   * Store vendor-specific metadata for a span.
+   * Note: This overwrites any existing metadata for the span.
+   * @param args.spanId - The span ID
+   * @param args.metadata - The vendor-specific metadata
+   */
+  addMetadata(args) {
+    this.#metadata.set(args.spanId, args.metadata);
+  }
+  /**
+   * Get vendor-specific metadata for a span.
+   * @param args.spanId - The span ID
+   * @returns The metadata, or undefined if not found
+   */
+  getMetadata(args) {
+    return this.#metadata.get(args.spanId);
+  }
+  // ============================================================================
+  // Parent Lookup Methods
+  // ============================================================================
+  /**
+   * Get the parent span or event for a given span.
+   * Looks up in both spans and events maps.
+   * @param args.span - The span to find the parent for
+   * @returns The parent span/event object, or undefined if root or not found
+   */
+  getParent(args) {
+    const parentId = args.span.parentSpanId;
+    if (parentId) {
+      if (this.#spans.has(parentId)) {
+        return this.#spans.get(parentId);
+      }
+      if (this.#events.has(parentId)) {
+        return this.#events.get(parentId);
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Get the parent span/event or fall back to the root object.
+   * Useful for vendors that attach child spans to either parent spans or the trace root.
+   * @param args.span - The span to find the parent for
+   * @returns The parent span/event, the root object, or undefined
+   */
+  getParentOrRoot(args) {
+    return this.getParent(args) ?? this.getRoot();
+  }
+};
+var DEFAULT_EARLY_QUEUE_MAX_ATTEMPTS = 5;
+var DEFAULT_EARLY_QUEUE_TTL_MS = 3e4;
+var DEFAULT_TRACE_CLEANUP_DELAY_MS = 3e4;
+var DEFAULT_MAX_PENDING_CLEANUP_TRACES = 100;
+var DEFAULT_MAX_TOTAL_TRACES = 500;
+var TrackingExporter = class extends BaseExporter {
+  /** Map of traceId to per-trace data container */
+  #traceMap = /* @__PURE__ */ new Map();
+  /** Flag to prevent processing during shutdown */
+  #shutdownStarted = false;
+  /** Flag to prevent concurrent hard cap enforcement */
+  #hardCapEnforcementInProgress = false;
+  /** Map of traceId to scheduled cleanup timeout */
+  #pendingCleanups = /* @__PURE__ */ new Map();
+  // Note: #traceMap maintains insertion order (JS Map spec), so we use
+  // #traceMap.keys() to iterate traces oldest-first for cap enforcement.
+  /** Subclass configuration with resolved values */
+  config;
+  /** Maximum attempts to process a queued event before dropping */
+  #earlyQueueMaxAttempts;
+  /** TTL in milliseconds for queued events */
+  #earlyQueueTTLMs;
+  /** Delay before cleaning up completed traces */
+  #traceCleanupDelayMs;
+  /** Soft cap on traces awaiting cleanup */
+  #maxPendingCleanupTraces;
+  /** Hard cap on total traces (will abort active spans if exceeded) */
+  #maxTotalTraces;
+  constructor(config) {
+    super(config);
+    this.config = config;
+    this.#earlyQueueMaxAttempts = config.earlyQueueMaxAttempts ?? DEFAULT_EARLY_QUEUE_MAX_ATTEMPTS;
+    this.#earlyQueueTTLMs = config.earlyQueueTTLMs ?? DEFAULT_EARLY_QUEUE_TTL_MS;
+    this.#traceCleanupDelayMs = config.traceCleanupDelayMs ?? DEFAULT_TRACE_CLEANUP_DELAY_MS;
+    this.#maxPendingCleanupTraces = config.maxPendingCleanupTraces ?? DEFAULT_MAX_PENDING_CLEANUP_TRACES;
+    this.#maxTotalTraces = config.maxTotalTraces ?? DEFAULT_MAX_TOTAL_TRACES;
+  }
+  // ============================================================================
+  // Early Queue Processing
+  // ============================================================================
+  /**
+   * Schedule async processing of events waiting for root span.
+   * Called after root span is successfully processed.
+   */
+  #scheduleProcessWaitingForRoot(traceId) {
+    setImmediate(() => {
+      this.#processWaitingForRoot(traceId).catch((error) => {
+        this.logger.error(`${this.name}: Error processing waiting-for-root queue`, { error, traceId });
+      });
+    });
+  }
+  /**
+   * Schedule async processing of events waiting for a specific parent span.
+   * Called after a span/event is successfully created.
+   */
+  #scheduleProcessWaitingFor(traceId, spanId) {
+    setImmediate(() => {
+      this.#processWaitingFor(traceId, spanId).catch((error) => {
+        this.logger.error(`${this.name}: Error processing waiting queue`, { error, traceId, spanId });
+      });
+    });
+  }
+  /**
+   * Process all events waiting for root span.
+   */
+  async #processWaitingForRoot(traceId) {
+    if (this.#shutdownStarted) return;
+    const traceData = this.#traceMap.get(traceId);
+    if (!traceData) return;
+    const queue = traceData.getEventsWaitingForRoot();
+    if (queue.length === 0) return;
+    this.logger.debug(`${this.name}: Processing ${queue.length} events waiting for root`, { traceId });
+    const toKeep = [];
+    const now = Date.now();
+    for (const queuedEvent of queue) {
+      if (now - queuedEvent.queuedAt.getTime() > this.#earlyQueueTTLMs) {
+        this.logger.warn(`${this.name}: Dropping event due to TTL expiry`, {
+          traceId,
+          spanId: queuedEvent.event.exportedSpan.id,
+          waitingFor: queuedEvent.waitingFor,
+          queuedAt: queuedEvent.queuedAt,
+          attempts: queuedEvent.attempts
+        });
+        continue;
+      }
+      if (queuedEvent.attempts >= this.#earlyQueueMaxAttempts) {
+        this.logger.warn(`${this.name}: Dropping event due to max attempts`, {
+          traceId,
+          spanId: queuedEvent.event.exportedSpan.id,
+          waitingFor: queuedEvent.waitingFor,
+          attempts: queuedEvent.attempts
+        });
+        continue;
+      }
+      queuedEvent.attempts++;
+      const processed = await this.#tryProcessQueuedEvent(queuedEvent, traceData);
+      if (!processed) {
+        const parentId = queuedEvent.event.exportedSpan.parentSpanId;
+        if (parentId && traceData.isRootProcessed()) {
+          traceData.addToWaitingQueue({
+            event: queuedEvent.event,
+            waitingFor: parentId,
+            attempts: queuedEvent.attempts,
+            queuedAt: queuedEvent.queuedAt
+          });
+        } else {
+          toKeep.push(queuedEvent);
+        }
+      }
+    }
+    traceData.clearWaitingForRoot();
+    for (const event of toKeep) {
+      traceData.addToWaitingQueue({
+        event: event.event,
+        waitingFor: "root",
+        attempts: event.attempts,
+        queuedAt: event.queuedAt
+      });
+    }
+  }
+  /**
+   * Process events waiting for a specific parent span.
+   */
+  async #processWaitingFor(traceId, spanId) {
+    if (this.#shutdownStarted) return;
+    const traceData = this.#traceMap.get(traceId);
+    if (!traceData) return;
+    const queue = traceData.getEventsWaitingFor({ spanId });
+    if (queue.length === 0) return;
+    this.logger.debug(`${this.name}: Processing ${queue.length} events waiting for span`, { traceId, spanId });
+    const toKeep = [];
+    const now = Date.now();
+    for (const queuedEvent of queue) {
+      if (now - queuedEvent.queuedAt.getTime() > this.#earlyQueueTTLMs) {
+        this.logger.warn(`${this.name}: Dropping event due to TTL expiry`, {
+          traceId,
+          spanId: queuedEvent.event.exportedSpan.id,
+          waitingFor: queuedEvent.waitingFor,
+          queuedAt: queuedEvent.queuedAt,
+          attempts: queuedEvent.attempts
+        });
+        continue;
+      }
+      if (queuedEvent.attempts >= this.#earlyQueueMaxAttempts) {
+        this.logger.warn(`${this.name}: Dropping event due to max attempts`, {
+          traceId,
+          spanId: queuedEvent.event.exportedSpan.id,
+          waitingFor: queuedEvent.waitingFor,
+          attempts: queuedEvent.attempts
+        });
+        continue;
+      }
+      queuedEvent.attempts++;
+      const processed = await this.#tryProcessQueuedEvent(queuedEvent, traceData);
+      if (!processed) {
+        toKeep.push(queuedEvent);
+      }
+    }
+    traceData.clearWaitingFor({ spanId });
+    for (const event of toKeep) {
+      traceData.addToWaitingQueue({
+        event: event.event,
+        waitingFor: spanId,
+        attempts: event.attempts,
+        queuedAt: event.queuedAt
+      });
+    }
+  }
+  /**
+   * Try to process a queued event.
+   * Returns true if successfully processed, false if still waiting for dependencies.
+   */
+  async #tryProcessQueuedEvent(queuedEvent, traceData) {
+    const { event } = queuedEvent;
+    const { exportedSpan } = event;
+    const method = this.getMethod(event);
+    try {
+      switch (method) {
+        case "handleEventSpan": {
+          traceData.addBranch({ spanId: exportedSpan.id, parentSpanId: exportedSpan.parentSpanId });
+          const eventData = await this._buildEvent({ span: exportedSpan, traceData });
+          if (eventData) {
+            if (!this.skipCachingEventSpans) {
+              traceData.addEvent({ eventId: exportedSpan.id, eventData });
+            }
+            this.#scheduleProcessWaitingFor(exportedSpan.traceId, exportedSpan.id);
+            return true;
+          }
+          return false;
+        }
+        case "handleSpanStart": {
+          traceData.addBranch({ spanId: exportedSpan.id, parentSpanId: exportedSpan.parentSpanId });
+          const spanData = await this._buildSpan({ span: exportedSpan, traceData });
+          if (spanData) {
+            traceData.addSpan({ spanId: exportedSpan.id, spanData });
+            if (exportedSpan.isRootSpan) {
+              traceData.markRootSpanProcessed();
+            }
+            this.#scheduleProcessWaitingFor(exportedSpan.traceId, exportedSpan.id);
+            return true;
+          }
+          return false;
+        }
+        case "handleSpanUpdate": {
+          await this._updateSpan({ span: exportedSpan, traceData });
+          return true;
+        }
+        case "handleSpanEnd": {
+          traceData.endSpan({ spanId: exportedSpan.id });
+          await this._finishSpan({ span: exportedSpan, traceData });
+          if (traceData.activeSpanCount() === 0) {
+            this.#scheduleCleanup(exportedSpan.traceId);
+          }
+          return true;
+        }
+        default:
+          return false;
+      }
+    } catch (error) {
+      this.logger.error(`${this.name}: Error processing queued event`, { error, event, method });
+      return false;
+    }
+  }
+  // ============================================================================
+  // Delayed Cleanup
+  // ============================================================================
+  /**
+   * Schedule cleanup of trace data after a delay.
+   * Allows late-arriving data to still be processed.
+   */
+  #scheduleCleanup(traceId) {
+    this.#cancelScheduledCleanup(traceId);
+    this.logger.debug(`${this.name}: Scheduling cleanup in ${this.#traceCleanupDelayMs}ms`, { traceId });
+    const timeout = setTimeout(() => {
+      this.#pendingCleanups.delete(traceId);
+      this.#performCleanup(traceId);
+    }, this.#traceCleanupDelayMs);
+    this.#pendingCleanups.set(traceId, timeout);
+    this.#enforcePendingCleanupCap();
+  }
+  /**
+   * Cancel a scheduled cleanup for a trace.
+   */
+  #cancelScheduledCleanup(traceId) {
+    const existingTimeout = this.#pendingCleanups.get(traceId);
+    if (existingTimeout) {
+      clearTimeout(existingTimeout);
+      this.#pendingCleanups.delete(traceId);
+      this.logger.debug(`${this.name}: Cancelled scheduled cleanup`, { traceId });
+    }
+  }
+  /**
+   * Perform the actual cleanup of trace data.
+   */
+  #performCleanup(traceId) {
+    const traceData = this.#traceMap.get(traceId);
+    if (!traceData) return;
+    const orphanedEvents = traceData.getAllQueuedEvents();
+    if (orphanedEvents.length > 0) {
+      this.logger.warn(`${this.name}: Dropping ${orphanedEvents.length} orphaned events on cleanup`, {
+        traceId,
+        orphanedEvents: orphanedEvents.map((e) => ({
+          spanId: e.event.exportedSpan.id,
+          waitingFor: e.waitingFor,
+          attempts: e.attempts,
+          queuedAt: e.queuedAt
+        }))
+      });
+    }
+    this.#traceMap.delete(traceId);
+    this.logger.debug(`${this.name}: Cleaned up trace data`, { traceId });
+  }
+  // ============================================================================
+  // Cap Enforcement
+  // ============================================================================
+  /**
+   * Enforce soft cap on pending cleanup traces.
+   * Only removes traces with activeSpanCount == 0.
+   */
+  #enforcePendingCleanupCap() {
+    if (this.#pendingCleanups.size <= this.#maxPendingCleanupTraces) {
+      return;
+    }
+    const toRemove = this.#pendingCleanups.size - this.#maxPendingCleanupTraces;
+    this.logger.warn(`${this.name}: Pending cleanup cap exceeded, force-cleaning ${toRemove} traces`, {
+      pendingCount: this.#pendingCleanups.size,
+      cap: this.#maxPendingCleanupTraces
+    });
+    let removed = 0;
+    for (const traceId of this.#traceMap.keys()) {
+      if (removed >= toRemove) break;
+      if (this.#pendingCleanups.has(traceId)) {
+        this.#cancelScheduledCleanup(traceId);
+        this.#performCleanup(traceId);
+        removed++;
+      }
+    }
+  }
+  /**
+   * Enforce hard cap on total traces.
+   * Will kill even active traces if necessary.
+   * Uses a flag to prevent concurrent executions when called fire-and-forget.
+   */
+  async #enforceHardCap() {
+    if (this.#traceMap.size <= this.#maxTotalTraces || this.#hardCapEnforcementInProgress) {
+      return;
+    }
+    this.#hardCapEnforcementInProgress = true;
+    try {
+      if (this.#traceMap.size <= this.#maxTotalTraces) {
+        return;
+      }
+      const toRemove = this.#traceMap.size - this.#maxTotalTraces;
+      this.logger.warn(`${this.name}: Total trace cap exceeded, killing ${toRemove} oldest traces`, {
+        traceCount: this.#traceMap.size,
+        cap: this.#maxTotalTraces
+      });
+      const reason = {
+        id: "TRACE_CAP_EXCEEDED",
+        message: "Trace killed due to memory cap enforcement.",
+        domain: "MASTRA_OBSERVABILITY",
+        category: "SYSTEM"
+      };
+      let removed = 0;
+      for (const traceId of [...this.#traceMap.keys()]) {
+        if (removed >= toRemove) break;
+        const traceData = this.#traceMap.get(traceId);
+        if (traceData) {
+          for (const spanId of traceData.activeSpanIds) {
+            const span = traceData.getSpan({ spanId });
+            if (span) {
+              await this._abortSpan({ span, traceData, reason });
+            }
+          }
+          this.#cancelScheduledCleanup(traceId);
+          this.#performCleanup(traceId);
+          removed++;
+        }
+      }
+    } finally {
+      this.#hardCapEnforcementInProgress = false;
+    }
+  }
+  // ============================================================================
+  // Lifecycle Hooks (Override in subclass)
+  // ============================================================================
+  /**
+   * Hook called before processing each tracing event.
+   * Override to transform or enrich the event before processing.
+   *
+   * Note: The customSpanFormatter is applied at the BaseExporter level before this hook.
+   * Subclasses can override this to add additional pre-processing logic.
+   *
+   * @param event - The incoming tracing event
+   * @returns The (possibly modified) event to process
+   */
+  async _preExportTracingEvent(event) {
+    return event;
+  }
+  /**
+   * Hook called after processing each tracing event.
+   * Override to perform post-processing actions like flushing.
+   */
+  async _postExportTracingEvent() {
+  }
+  // ============================================================================
+  // Behavior Flags (Override in subclass as needed)
+  // ============================================================================
+  /**
+   * If true, skip calling _buildRoot and let root spans go through _buildSpan.
+   * Use when the vendor doesn't have a separate trace/root concept.
+   * @default false
+   */
+  skipBuildRootTask = false;
+  /**
+   * If true, skip processing span_updated events entirely.
+   * Use when the vendor doesn't support incremental span updates.
+   * @default false
+   */
+  skipSpanUpdateEvents = false;
+  /**
+   * If true, don't cache event spans in TraceData.
+   * Use when events can't be parents of other spans.
+   * @default false
+   */
+  skipCachingEventSpans = false;
+  getMethod(event) {
+    if (event.exportedSpan.isEvent) {
+      return "handleEventSpan";
+    }
+    const eventType = event.type;
+    switch (eventType) {
+      case observability.TracingEventType.SPAN_STARTED:
+        return "handleSpanStart";
+      case observability.TracingEventType.SPAN_UPDATED:
+        return "handleSpanUpdate";
+      case observability.TracingEventType.SPAN_ENDED:
+        return "handleSpanEnd";
+      default: {
+        const _exhaustiveCheck = eventType;
+        throw new Error(`Unhandled event type: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+  async _exportTracingEvent(event) {
+    if (this.#shutdownStarted) {
+      return;
+    }
+    const method = this.getMethod(event);
+    if (method == "handleSpanUpdate" && this.skipSpanUpdateEvents) {
+      return;
+    }
+    const traceId = event.exportedSpan.traceId;
+    const traceData = this.getTraceData({ traceId, method });
+    const { exportedSpan } = await this._preExportTracingEvent(event);
+    if (!this.skipBuildRootTask && !traceData.hasRoot()) {
+      if (exportedSpan.isRootSpan) {
+        this.logger.debug(`${this.name}: Building root`, {
+          traceId: exportedSpan.traceId,
+          spanId: exportedSpan.id
+        });
+        const rootData = await this._buildRoot({ span: exportedSpan, traceData });
+        if (rootData) {
+          this.logger.debug(`${this.name}: Adding root`, {
+            traceId: exportedSpan.traceId,
+            spanId: exportedSpan.id
+          });
+          traceData.addRoot({ rootId: exportedSpan.id, rootData });
+          this.#scheduleProcessWaitingForRoot(traceId);
+        }
+      } else {
+        this.logger.debug(`${this.name}: Root does not exist, adding span to waiting queue.`, {
+          traceId: exportedSpan.traceId,
+          spanId: exportedSpan.id
+        });
+        traceData.addToWaitingQueue({ event, waitingFor: "root" });
+        return;
+      }
+    }
+    if (exportedSpan.metadata && this.name in exportedSpan.metadata) {
+      const metadata = exportedSpan.metadata[this.name];
+      this.logger.debug(`${this.name}: Found provider metadata in span`, {
+        traceId: exportedSpan.traceId,
+        spanId: exportedSpan.id,
+        metadata
+      });
+      traceData.addMetadata({ spanId: exportedSpan.id, metadata });
+    }
+    try {
+      switch (method) {
+        case "handleEventSpan": {
+          this.logger.debug(`${this.name}: handling event`, {
+            traceId: exportedSpan.traceId,
+            spanId: exportedSpan.id
+          });
+          traceData.addBranch({ spanId: exportedSpan.id, parentSpanId: exportedSpan.parentSpanId });
+          const eventData = await this._buildEvent({ span: exportedSpan, traceData });
+          if (eventData) {
+            if (!this.skipCachingEventSpans) {
+              this.logger.debug(`${this.name}: adding event to traceData`, {
+                traceId: exportedSpan.traceId,
+                spanId: exportedSpan.id
+              });
+              traceData.addEvent({ eventId: exportedSpan.id, eventData });
+            }
+            this.#scheduleProcessWaitingFor(traceId, exportedSpan.id);
+          } else {
+            const parentId = exportedSpan.parentSpanId;
+            this.logger.debug(`${this.name}: adding event to waiting queue`, {
+              traceId: exportedSpan.traceId,
+              spanId: exportedSpan.id,
+              waitingFor: parentId ?? "root"
+            });
+            traceData.addToWaitingQueue({ event, waitingFor: parentId ?? "root" });
+          }
+          break;
+        }
+        case "handleSpanStart": {
+          this.logger.debug(`${this.name}: handling span start`, {
+            traceId: exportedSpan.traceId,
+            spanId: exportedSpan.id
+          });
+          traceData.addBranch({ spanId: exportedSpan.id, parentSpanId: exportedSpan.parentSpanId });
+          const spanData = await this._buildSpan({ span: exportedSpan, traceData });
+          if (spanData) {
+            this.logger.debug(`${this.name}: adding span to traceData`, {
+              traceId: exportedSpan.traceId,
+              spanId: exportedSpan.id
+            });
+            traceData.addSpan({ spanId: exportedSpan.id, spanData });
+            if (exportedSpan.isRootSpan) {
+              traceData.markRootSpanProcessed();
+              this.#scheduleProcessWaitingForRoot(traceId);
+            }
+            this.#scheduleProcessWaitingFor(traceId, exportedSpan.id);
+          } else {
+            const parentId = exportedSpan.parentSpanId;
+            this.logger.debug(`${this.name}: adding span to waiting queue`, {
+              traceId: exportedSpan.traceId,
+              waitingFor: parentId ?? "root"
+            });
+            traceData.addToWaitingQueue({ event, waitingFor: parentId ?? "root" });
+          }
+          break;
+        }
+        case "handleSpanUpdate":
+          this.logger.debug(`${this.name}: handling span update`, {
+            traceId: exportedSpan.traceId,
+            spanId: exportedSpan.id
+          });
+          await this._updateSpan({ span: exportedSpan, traceData });
+          break;
+        case "handleSpanEnd":
+          this.logger.debug(`${this.name}: handling span end`, {
+            traceId: exportedSpan.traceId,
+            spanId: exportedSpan.id
+          });
+          traceData.endSpan({ spanId: exportedSpan.id });
+          await this._finishSpan({ span: exportedSpan, traceData });
+          if (traceData.activeSpanCount() === 0) {
+            this.#scheduleCleanup(traceId);
+          }
+          break;
+      }
+    } catch (error) {
+      this.logger.error(`${this.name}: exporter error`, { error, event, method });
+    }
+    if (traceData.activeSpanCount() === 0) {
+      this.#scheduleCleanup(traceId);
+    }
+    await this._postExportTracingEvent();
+  }
+  // ============================================================================
+  // Protected Helpers
+  // ============================================================================
+  /**
+   * Get or create the TraceData container for a trace.
+   * Also cancels any pending cleanup since new data has arrived.
+   *
+   * @param args.traceId - The trace ID
+   * @param args.method - The calling method name (for logging)
+   * @returns The TraceData container for this trace
+   */
+  getTraceData(args) {
+    const { traceId, method } = args;
+    this.#cancelScheduledCleanup(traceId);
+    if (!this.#traceMap.has(traceId)) {
+      this.#traceMap.set(traceId, new TraceData());
+      this.logger.debug(`${this.name}: Created new trace data cache`, {
+        traceId,
+        method
+      });
+      this.#enforceHardCap().catch((error) => {
+        this.logger.error(`${this.name}: Error enforcing hard cap`, { error });
+      });
+    }
+    return this.#traceMap.get(traceId);
+  }
+  /**
+   * Get the current number of traces being tracked.
+   * @returns The trace count
+   */
+  traceMapSize() {
+    return this.#traceMap.size;
+  }
+  // ============================================================================
+  // Flush and Shutdown Hooks (Override in subclass as needed)
+  // ============================================================================
+  /**
+   * Hook called by flush() to perform vendor-specific flush logic.
+   * Override to send buffered data to the vendor's API.
+   *
+   * Unlike _postShutdown(), this method should NOT release resources,
+   * as the exporter will continue to be used after flushing.
+   */
+  async _flush() {
+  }
+  /**
+   * Force flush any buffered data without shutting down the exporter.
+   * This is useful in serverless environments where you need to ensure spans
+   * are exported before the runtime instance is terminated.
+   *
+   * Subclasses should override _flush() to implement vendor-specific flush logic.
+   */
+  async flush() {
+    if (this.isDisabled) {
+      return;
+    }
+    this.logger.debug(`${this.name}: Flushing`);
+    await this._flush();
+  }
+  /**
+   * Hook called at the start of shutdown, before cancelling timers and aborting spans.
+   * Override to perform vendor-specific pre-shutdown tasks.
+   */
+  async _preShutdown() {
+  }
+  /**
+   * Hook called at the end of shutdown, after all spans are aborted.
+   * Override to perform vendor-specific cleanup (e.g., flushing).
+   */
+  async _postShutdown() {
+  }
+  /**
+   * Gracefully shut down the exporter.
+   * Cancels all pending cleanup timers, aborts all active spans, and clears state.
+   */
+  async shutdown() {
+    if (this.isDisabled) {
+      return;
+    }
+    this.#shutdownStarted = true;
+    await this._preShutdown();
+    for (const [traceId, timeout] of this.#pendingCleanups) {
+      clearTimeout(timeout);
+      this.logger.debug(`${this.name}: Cancelled pending cleanup on shutdown`, { traceId });
+    }
+    this.#pendingCleanups.clear();
+    const reason = {
+      id: "SHUTDOWN",
+      message: "Observability is shutting down.",
+      domain: "MASTRA_OBSERVABILITY",
+      category: "SYSTEM"
+    };
+    for (const [traceId, traceData] of this.#traceMap) {
+      const orphanedEvents = traceData.getAllQueuedEvents();
+      if (orphanedEvents.length > 0) {
+        this.logger.warn(`${this.name}: Dropping ${orphanedEvents.length} orphaned events on shutdown`, {
+          traceId,
+          orphanedEvents: orphanedEvents.map((e) => ({
+            spanId: e.event.exportedSpan.id,
+            waitingFor: e.waitingFor,
+            attempts: e.attempts
+          }))
+        });
+      }
+      for (const spanId of traceData.activeSpanIds) {
+        const span = traceData.getSpan({ spanId });
+        if (span) {
+          await this._abortSpan({ span, traceData, reason });
+        }
+      }
+    }
+    this.#traceMap.clear();
+    await this._postShutdown();
+    await super.shutdown();
+  }
+};
+
+// src/exporters/span-formatters.ts
+function chainFormatters(formatters) {
+  return async (span) => {
+    let currentSpan = span;
+    for (const formatter of formatters) {
+      currentSpan = await formatter(currentSpan);
+    }
+    return currentSpan;
+  };
+}
+var CloudExporter = class extends BaseExporter {
+  name = "mastra-cloud-observability-exporter";
+  cloudConfig;
+  buffer;
+  flushTimer = null;
+  constructor(config = {}) {
+    super(config);
+    const accessToken = config.accessToken ?? process.env.MASTRA_CLOUD_ACCESS_TOKEN;
+    if (!accessToken) {
+      this.setDisabled("MASTRA_CLOUD_ACCESS_TOKEN environment variable not set.");
+    }
+    const endpoint = config.endpoint ?? process.env.MASTRA_CLOUD_TRACES_ENDPOINT ?? "https://api.mastra.ai/ai/spans/publish";
+    this.cloudConfig = {
+      logger: this.logger,
+      logLevel: config.logLevel ?? logger.LogLevel.INFO,
+      maxBatchSize: config.maxBatchSize ?? 1e3,
+      maxBatchWaitMs: config.maxBatchWaitMs ?? 5e3,
+      maxRetries: config.maxRetries ?? 3,
+      accessToken: accessToken || "",
+      endpoint
+    };
+    this.buffer = {
+      spans: [],
+      totalSize: 0
+    };
+  }
+  async _exportTracingEvent(event) {
+    if (event.type !== observability.TracingEventType.SPAN_ENDED) {
+      return;
+    }
+    this.addToBuffer(event);
+    if (this.shouldFlush()) {
+      this.flush().catch((error) => {
+        this.logger.error("Batch flush failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    } else if (this.buffer.totalSize === 1) {
+      this.scheduleFlush();
+    }
+  }
+  addToBuffer(event) {
+    if (this.buffer.totalSize === 0) {
+      this.buffer.firstEventTime = /* @__PURE__ */ new Date();
+    }
+    const spanRecord = this.formatSpan(event.exportedSpan);
+    this.buffer.spans.push(spanRecord);
+    this.buffer.totalSize++;
+  }
+  formatSpan(span) {
+    const spanRecord = {
+      traceId: span.traceId,
+      spanId: span.id,
+      parentSpanId: span.parentSpanId ?? null,
+      name: span.name,
+      spanType: span.type,
+      attributes: span.attributes ?? null,
+      metadata: span.metadata ?? null,
+      startedAt: span.startTime,
+      endedAt: span.endTime ?? null,
+      input: span.input ?? null,
+      output: span.output ?? null,
+      error: span.errorInfo,
+      isEvent: span.isEvent,
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: null
+    };
+    return spanRecord;
+  }
+  shouldFlush() {
+    if (this.buffer.totalSize >= this.cloudConfig.maxBatchSize) {
+      return true;
+    }
+    if (this.buffer.firstEventTime && this.buffer.totalSize > 0) {
+      const elapsed = Date.now() - this.buffer.firstEventTime.getTime();
+      if (elapsed >= this.cloudConfig.maxBatchWaitMs) {
+        return true;
+      }
+    }
+    return false;
+  }
+  scheduleFlush() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+    }
+    this.flushTimer = setTimeout(() => {
+      this.flush().catch((error$1) => {
+        const mastraError = new error.MastraError(
+          {
+            id: `CLOUD_EXPORTER_FAILED_TO_SCHEDULE_FLUSH`,
+            domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
+            category: error.ErrorCategory.USER
+          },
+          error$1
+        );
+        this.logger.trackException(mastraError);
+        this.logger.error("Scheduled flush failed", mastraError);
+      });
+    }, this.cloudConfig.maxBatchWaitMs);
+  }
+  async flushBuffer() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.buffer.totalSize === 0) {
+      return;
+    }
+    const startTime = Date.now();
+    const spansCopy = [...this.buffer.spans];
+    const flushReason = this.buffer.totalSize >= this.cloudConfig.maxBatchSize ? "size" : "time";
+    this.resetBuffer();
+    try {
+      await this.batchUpload(spansCopy);
+      const elapsed = Date.now() - startTime;
+      this.logger.debug("Batch flushed successfully", {
+        batchSize: spansCopy.length,
+        flushReason,
+        durationMs: elapsed
+      });
+    } catch (error$1) {
+      const mastraError = new error.MastraError(
+        {
+          id: `CLOUD_EXPORTER_FAILED_TO_BATCH_UPLOAD`,
+          domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
+          category: error.ErrorCategory.USER,
+          details: {
+            droppedBatchSize: spansCopy.length
+          }
+        },
+        error$1
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Batch upload failed after all retries, dropping batch", mastraError);
+    }
+  }
+  /**
+   * Uploads spans to cloud API using fetchWithRetry for all retry logic
+   */
+  async batchUpload(spans) {
+    const headers = {
+      Authorization: `Bearer ${this.cloudConfig.accessToken}`,
+      "Content-Type": "application/json"
+    };
+    const options = {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ spans })
+    };
+    await utils.fetchWithRetry(this.cloudConfig.endpoint, options, this.cloudConfig.maxRetries);
+  }
+  resetBuffer() {
+    this.buffer.spans = [];
+    this.buffer.firstEventTime = void 0;
+    this.buffer.totalSize = 0;
+  }
+  /**
+   * Force flush any buffered spans without shutting down the exporter.
+   * This is useful in serverless environments where you need to ensure spans
+   * are exported before the runtime instance is terminated.
+   */
+  async flush() {
+    if (this.isDisabled) {
+      return;
+    }
+    if (this.buffer.totalSize > 0) {
+      this.logger.debug("Flushing buffered events", {
+        bufferedEvents: this.buffer.totalSize
+      });
+      await this.flushBuffer();
+    }
+  }
+  async shutdown() {
+    if (this.isDisabled) {
+      return;
+    }
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    try {
+      await this.flush();
+    } catch (error$1) {
+      const mastraError = new error.MastraError(
+        {
+          id: `CLOUD_EXPORTER_FAILED_TO_FLUSH_REMAINING_EVENTS_DURING_SHUTDOWN`,
+          domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
+          category: error.ErrorCategory.USER,
+          details: {
+            remainingEvents: this.buffer.totalSize
+          }
+        },
+        error$1
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to flush remaining events during shutdown", mastraError);
+    }
+    this.logger.info("CloudExporter shutdown complete");
+  }
+};
+var ConsoleExporter = class extends BaseExporter {
+  name = "tracing-console-exporter";
+  constructor(config = {}) {
+    super(config);
+  }
+  async _exportTracingEvent(event) {
+    const span = event.exportedSpan;
+    const formatAttributes = (attributes) => {
+      try {
+        return JSON.stringify(attributes, null, 2);
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : "Unknown formatting error";
+        return `[Unable to serialize attributes: ${errMsg}]`;
+      }
+    };
+    const formatDuration = (startTime, endTime) => {
+      if (!endTime) return "N/A";
+      const duration = endTime.getTime() - startTime.getTime();
+      return `${duration}ms`;
+    };
+    switch (event.type) {
+      case observability.TracingEventType.SPAN_STARTED:
+        this.logger.info(`\u{1F680} SPAN_STARTED`);
+        this.logger.info(`   Type: ${span.type}`);
+        this.logger.info(`   Name: ${span.name}`);
+        this.logger.info(`   ID: ${span.id}`);
+        this.logger.info(`   Trace ID: ${span.traceId}`);
+        if (span.input !== void 0) {
+          this.logger.info(`   Input: ${formatAttributes(span.input)}`);
+        }
+        this.logger.info(`   Attributes: ${formatAttributes(span.attributes)}`);
+        this.logger.info("\u2500".repeat(80));
+        break;
+      case observability.TracingEventType.SPAN_ENDED:
+        const duration = formatDuration(span.startTime, span.endTime);
+        this.logger.info(`\u2705 SPAN_ENDED`);
+        this.logger.info(`   Type: ${span.type}`);
+        this.logger.info(`   Name: ${span.name}`);
+        this.logger.info(`   ID: ${span.id}`);
+        this.logger.info(`   Duration: ${duration}`);
+        this.logger.info(`   Trace ID: ${span.traceId}`);
+        if (span.input !== void 0) {
+          this.logger.info(`   Input: ${formatAttributes(span.input)}`);
+        }
+        if (span.output !== void 0) {
+          this.logger.info(`   Output: ${formatAttributes(span.output)}`);
+        }
+        if (span.errorInfo) {
+          this.logger.info(`   Error: ${formatAttributes(span.errorInfo)}`);
+        }
+        this.logger.info(`   Attributes: ${formatAttributes(span.attributes)}`);
+        this.logger.info("\u2500".repeat(80));
+        break;
+      case observability.TracingEventType.SPAN_UPDATED:
+        this.logger.info(`\u{1F4DD} SPAN_UPDATED`);
         this.logger.info(`   Type: ${span.type}`);
         this.logger.info(`   Name: ${span.name}`);
         this.logger.info(`   ID: ${span.id}`);
-        this.logger.info(`   Duration: ${duration}`);
         this.logger.info(`   Trace ID: ${span.traceId}`);
         if (span.input !== void 0) {
           this.logger.info(`   Input: ${formatAttributes(span.input)}`);
         }
-        if (span.output !== void 0) {
-          this.logger.info(`   Output: ${formatAttributes(span.output)}`);
+        if (span.output !== void 0) {
+          this.logger.info(`   Output: ${formatAttributes(span.output)}`);
+        }
+        if (span.errorInfo) {
+          this.logger.info(`   Error: ${formatAttributes(span.errorInfo)}`);
+        }
+        this.logger.info(`   Updated Attributes: ${formatAttributes(span.attributes)}`);
+        this.logger.info("\u2500".repeat(80));
+        break;
+      default:
+        this.logger.warn(`Tracing event type not implemented: ${event.type}`);
+    }
+  }
+  async shutdown() {
+    this.logger.info("ConsoleExporter shutdown");
+  }
+};
+function resolveTracingStorageStrategy(config, observability, storageName, logger) {
+  if (config.strategy && config.strategy !== "auto") {
+    const hints = observability.tracingStrategy;
+    if (hints.supported.includes(config.strategy)) {
+      return config.strategy;
+    }
+    logger.warn("User-specified tracing strategy not supported by storage adapter, falling back to auto-selection", {
+      userStrategy: config.strategy,
+      storageAdapter: storageName,
+      supportedStrategies: hints.supported,
+      fallbackStrategy: hints.preferred
+    });
+  }
+  return observability.tracingStrategy.preferred;
+}
+function getStringOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+function getObjectOrNull(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+var DefaultExporter = class extends BaseExporter {
+  name = "mastra-default-observability-exporter";
+  #storage;
+  #observability;
+  #config;
+  #resolvedStrategy;
+  buffer;
+  #flushTimer = null;
+  // Track all spans that have been created, persists across flushes
+  allCreatedSpans = /* @__PURE__ */ new Set();
+  constructor(config = {}) {
+    super(config);
+    if (config === void 0) {
+      config = {};
+    }
+    this.#config = {
+      ...config,
+      maxBatchSize: config.maxBatchSize ?? 1e3,
+      maxBufferSize: config.maxBufferSize ?? 1e4,
+      maxBatchWaitMs: config.maxBatchWaitMs ?? 5e3,
+      maxRetries: config.maxRetries ?? 4,
+      retryDelayMs: config.retryDelayMs ?? 500,
+      strategy: config.strategy ?? "auto"
+    };
+    this.buffer = {
+      creates: [],
+      updates: [],
+      insertOnly: [],
+      seenSpans: /* @__PURE__ */ new Set(),
+      spanSequences: /* @__PURE__ */ new Map(),
+      completedSpans: /* @__PURE__ */ new Set(),
+      outOfOrderCount: 0,
+      totalSize: 0
+    };
+    this.#resolvedStrategy = "batch-with-updates";
+  }
+  #strategyInitialized = false;
+  /**
+   * Initialize the exporter (called after all dependencies are ready)
+   */
+  async init(options) {
+    this.#storage = options.mastra?.getStorage();
+    if (!this.#storage) {
+      this.logger.warn("DefaultExporter disabled: Storage not available. Traces will not be persisted.");
+      return;
+    }
+    this.#observability = await this.#storage.getStore("observability");
+    if (!this.#observability) {
+      this.logger.warn("DefaultExporter disabled: Observability storage not available. Traces will not be persisted.");
+      return;
+    }
+    this.initializeStrategy(this.#observability, this.#storage.constructor.name);
+  }
+  /**
+   * Initialize the resolved strategy once observability store is available
+   */
+  initializeStrategy(observability, storageName) {
+    if (this.#strategyInitialized) return;
+    this.#resolvedStrategy = resolveTracingStorageStrategy(this.#config, observability, storageName, this.logger);
+    this.#strategyInitialized = true;
+    this.logger.debug("tracing storage exporter initialized", {
+      strategy: this.#resolvedStrategy,
+      source: this.#config.strategy !== "auto" ? "user" : "auto",
+      storageAdapter: storageName,
+      maxBatchSize: this.#config.maxBatchSize,
+      maxBatchWaitMs: this.#config.maxBatchWaitMs
+    });
+  }
+  /**
+   * Builds a unique span key for tracking
+   */
+  buildSpanKey(traceId, spanId) {
+    return `${traceId}:${spanId}`;
+  }
+  /**
+   * Gets the next sequence number for a span
+   */
+  getNextSequence(spanKey) {
+    const current = this.buffer.spanSequences.get(spanKey) || 0;
+    const next = current + 1;
+    this.buffer.spanSequences.set(spanKey, next);
+    return next;
+  }
+  /**
+   * Handles out-of-order span updates by logging and skipping
+   */
+  handleOutOfOrderUpdate(event) {
+    this.logger.warn("Out-of-order span update detected - skipping event", {
+      spanId: event.exportedSpan.id,
+      traceId: event.exportedSpan.traceId,
+      spanName: event.exportedSpan.name,
+      eventType: event.type
+    });
+  }
+  /**
+   * Adds an event to the appropriate buffer based on strategy
+   */
+  addToBuffer(event) {
+    const spanKey = this.buildSpanKey(event.exportedSpan.traceId, event.exportedSpan.id);
+    if (this.buffer.totalSize === 0) {
+      this.buffer.firstEventTime = /* @__PURE__ */ new Date();
+    }
+    switch (event.type) {
+      case observability.TracingEventType.SPAN_STARTED:
+        if (this.#resolvedStrategy === "batch-with-updates") {
+          const createRecord = this.buildCreateRecord(event.exportedSpan);
+          this.buffer.creates.push(createRecord);
+          this.buffer.seenSpans.add(spanKey);
+          this.allCreatedSpans.add(spanKey);
+        }
+        break;
+      case observability.TracingEventType.SPAN_UPDATED:
+        if (this.#resolvedStrategy === "batch-with-updates") {
+          if (this.allCreatedSpans.has(spanKey)) {
+            this.buffer.updates.push({
+              traceId: event.exportedSpan.traceId,
+              spanId: event.exportedSpan.id,
+              updates: this.buildUpdateRecord(event.exportedSpan),
+              sequenceNumber: this.getNextSequence(spanKey)
+            });
+          } else {
+            this.handleOutOfOrderUpdate(event);
+            this.buffer.outOfOrderCount++;
+          }
+        }
+        break;
+      case observability.TracingEventType.SPAN_ENDED:
+        if (this.#resolvedStrategy === "batch-with-updates") {
+          if (this.allCreatedSpans.has(spanKey)) {
+            this.buffer.updates.push({
+              traceId: event.exportedSpan.traceId,
+              spanId: event.exportedSpan.id,
+              updates: this.buildUpdateRecord(event.exportedSpan),
+              sequenceNumber: this.getNextSequence(spanKey)
+            });
+            this.buffer.completedSpans.add(spanKey);
+          } else if (event.exportedSpan.isEvent) {
+            const createRecord = this.buildCreateRecord(event.exportedSpan);
+            this.buffer.creates.push(createRecord);
+            this.buffer.seenSpans.add(spanKey);
+            this.allCreatedSpans.add(spanKey);
+            this.buffer.completedSpans.add(spanKey);
+          } else {
+            this.handleOutOfOrderUpdate(event);
+            this.buffer.outOfOrderCount++;
+          }
+        } else if (this.#resolvedStrategy === "insert-only") {
+          const createRecord = this.buildCreateRecord(event.exportedSpan);
+          this.buffer.insertOnly.push(createRecord);
+          this.buffer.completedSpans.add(spanKey);
+          this.allCreatedSpans.add(spanKey);
+        }
+        break;
+    }
+    this.buffer.totalSize = this.buffer.creates.length + this.buffer.updates.length + this.buffer.insertOnly.length;
+  }
+  /**
+   * Checks if buffer should be flushed based on size or time triggers
+   */
+  shouldFlush() {
+    if (this.buffer.totalSize >= this.#config.maxBufferSize) {
+      return true;
+    }
+    if (this.buffer.totalSize >= this.#config.maxBatchSize) {
+      return true;
+    }
+    if (this.buffer.firstEventTime && this.buffer.totalSize > 0) {
+      const elapsed = Date.now() - this.buffer.firstEventTime.getTime();
+      if (elapsed >= this.#config.maxBatchWaitMs) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Resets the buffer after successful flush
+   */
+  resetBuffer(completedSpansToCleanup = /* @__PURE__ */ new Set()) {
+    this.buffer.creates = [];
+    this.buffer.updates = [];
+    this.buffer.insertOnly = [];
+    this.buffer.seenSpans.clear();
+    this.buffer.spanSequences.clear();
+    this.buffer.completedSpans.clear();
+    this.buffer.outOfOrderCount = 0;
+    this.buffer.firstEventTime = void 0;
+    this.buffer.totalSize = 0;
+    for (const spanKey of completedSpansToCleanup) {
+      this.allCreatedSpans.delete(spanKey);
+    }
+  }
+  /**
+   * Schedules a flush using setTimeout
+   */
+  scheduleFlush() {
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+    }
+    this.#flushTimer = setTimeout(() => {
+      this.flushBuffer().catch((error) => {
+        this.logger.error("Scheduled flush failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    }, this.#config.maxBatchWaitMs);
+  }
+  /**
+   * Serializes span attributes to storage record format
+   * Handles all Span types and their specific attributes
+   */
+  serializeAttributes(span) {
+    if (!span.attributes) {
+      return null;
+    }
+    try {
+      return JSON.parse(
+        JSON.stringify(span.attributes, (_key, value) => {
+          if (value instanceof Date) {
+            return value.toISOString();
+          }
+          if (typeof value === "object" && value !== null) {
+            return value;
+          }
+          return value;
+        })
+      );
+    } catch (error) {
+      this.logger.warn("Failed to serialize span attributes, storing as null", {
+        spanId: span.id,
+        spanType: span.type,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return null;
+    }
+  }
+  buildCreateRecord(span) {
+    const metadata = span.metadata ?? {};
+    return {
+      traceId: span.traceId,
+      spanId: span.id,
+      parentSpanId: span.parentSpanId ?? null,
+      name: span.name,
+      // Entity identification - from span
+      entityType: span.entityType ?? null,
+      entityId: span.entityId ?? null,
+      entityName: span.entityName ?? null,
+      // Identity & Tenancy - extracted from metadata if present
+      userId: getStringOrNull(metadata.userId),
+      organizationId: getStringOrNull(metadata.organizationId),
+      resourceId: getStringOrNull(metadata.resourceId),
+      // Correlation IDs - extracted from metadata if present
+      runId: getStringOrNull(metadata.runId),
+      sessionId: getStringOrNull(metadata.sessionId),
+      threadId: getStringOrNull(metadata.threadId),
+      requestId: getStringOrNull(metadata.requestId),
+      // Deployment context - extracted from metadata if present
+      environment: getStringOrNull(metadata.environment),
+      source: getStringOrNull(metadata.source),
+      serviceName: getStringOrNull(metadata.serviceName),
+      scope: getObjectOrNull(metadata.scope),
+      // Span data
+      spanType: span.type,
+      attributes: this.serializeAttributes(span),
+      metadata: span.metadata ?? null,
+      // Keep all metadata including extracted fields
+      tags: span.tags ?? null,
+      links: null,
+      input: span.input ?? null,
+      output: span.output ?? null,
+      error: span.errorInfo ?? null,
+      isEvent: span.isEvent,
+      // Timestamps
+      startedAt: span.startTime,
+      endedAt: span.endTime ?? null
+    };
+  }
+  buildUpdateRecord(span) {
+    return {
+      name: span.name,
+      scope: null,
+      attributes: this.serializeAttributes(span),
+      metadata: span.metadata ?? null,
+      links: null,
+      endedAt: span.endTime ?? null,
+      input: span.input,
+      output: span.output,
+      error: span.errorInfo ?? null
+    };
+  }
+  /**
+   * Handles realtime strategy - processes each event immediately
+   */
+  async handleRealtimeEvent(event, observability$1) {
+    const span = event.exportedSpan;
+    const spanKey = this.buildSpanKey(span.traceId, span.id);
+    if (span.isEvent) {
+      if (event.type === observability.TracingEventType.SPAN_ENDED) {
+        await observability$1.createSpan({ span: this.buildCreateRecord(event.exportedSpan) });
+      } else {
+        this.logger.warn(`Tracing event type not implemented for event spans: ${event.type}`);
+      }
+    } else {
+      switch (event.type) {
+        case observability.TracingEventType.SPAN_STARTED:
+          await observability$1.createSpan({ span: this.buildCreateRecord(event.exportedSpan) });
+          this.allCreatedSpans.add(spanKey);
+          break;
+        case observability.TracingEventType.SPAN_UPDATED:
+          await observability$1.updateSpan({
+            traceId: span.traceId,
+            spanId: span.id,
+            updates: this.buildUpdateRecord(span)
+          });
+          break;
+        case observability.TracingEventType.SPAN_ENDED:
+          await observability$1.updateSpan({
+            traceId: span.traceId,
+            spanId: span.id,
+            updates: this.buildUpdateRecord(span)
+          });
+          this.allCreatedSpans.delete(spanKey);
+          break;
+        default:
+          this.logger.warn(`Tracing event type not implemented for span spans: ${event.type}`);
+      }
+    }
+  }
+  /**
+   * Handles batch-with-updates strategy - buffers events and processes in batches
+   */
+  handleBatchWithUpdatesEvent(event) {
+    this.addToBuffer(event);
+    if (this.shouldFlush()) {
+      this.flushBuffer().catch((error) => {
+        this.logger.error("Batch flush failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    } else if (this.buffer.totalSize === 1) {
+      this.scheduleFlush();
+    }
+  }
+  /**
+   * Handles insert-only strategy - only processes SPAN_ENDED events in batches
+   */
+  handleInsertOnlyEvent(event) {
+    if (event.type === observability.TracingEventType.SPAN_ENDED) {
+      this.addToBuffer(event);
+      if (this.shouldFlush()) {
+        this.flushBuffer().catch((error) => {
+          this.logger.error("Batch flush failed", {
+            error: error instanceof Error ? error.message : String(error)
+          });
+        });
+      } else if (this.buffer.totalSize === 1) {
+        this.scheduleFlush();
+      }
+    }
+  }
+  /**
+   * Calculates retry delay using exponential backoff
+   */
+  calculateRetryDelay(attempt) {
+    return this.#config.retryDelayMs * Math.pow(2, attempt);
+  }
+  /**
+   * Flushes the current buffer to storage with retry logic (internal implementation)
+   */
+  async flushBuffer() {
+    if (!this.#observability) {
+      this.logger.debug("Cannot flush traces. Observability storage is not initialized");
+      return;
+    }
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+      this.#flushTimer = null;
+    }
+    if (this.buffer.totalSize === 0) {
+      return;
+    }
+    const startTime = Date.now();
+    const flushReason = this.buffer.totalSize >= this.#config.maxBufferSize ? "overflow" : this.buffer.totalSize >= this.#config.maxBatchSize ? "size" : "time";
+    const bufferCopy = {
+      creates: [...this.buffer.creates],
+      updates: [...this.buffer.updates],
+      insertOnly: [...this.buffer.insertOnly],
+      seenSpans: new Set(this.buffer.seenSpans),
+      spanSequences: new Map(this.buffer.spanSequences),
+      completedSpans: new Set(this.buffer.completedSpans),
+      outOfOrderCount: this.buffer.outOfOrderCount,
+      firstEventTime: this.buffer.firstEventTime,
+      totalSize: this.buffer.totalSize
+    };
+    this.resetBuffer();
+    await this.flushWithRetries(this.#observability, bufferCopy, 0);
+    const elapsed = Date.now() - startTime;
+    this.logger.debug("Batch flushed", {
+      strategy: this.#resolvedStrategy,
+      batchSize: bufferCopy.totalSize,
+      flushReason,
+      durationMs: elapsed,
+      outOfOrderCount: bufferCopy.outOfOrderCount > 0 ? bufferCopy.outOfOrderCount : void 0
+    });
+  }
+  /**
+   * Attempts to flush with exponential backoff retry logic
+   */
+  async flushWithRetries(observability, buffer, attempt) {
+    try {
+      if (this.#resolvedStrategy === "batch-with-updates") {
+        if (buffer.creates.length > 0) {
+          await observability.batchCreateSpans({ records: buffer.creates });
+        }
+        if (buffer.updates.length > 0) {
+          const sortedUpdates = buffer.updates.sort((a, b) => {
+            const spanCompare = this.buildSpanKey(a.traceId, a.spanId).localeCompare(
+              this.buildSpanKey(b.traceId, b.spanId)
+            );
+            if (spanCompare !== 0) return spanCompare;
+            return a.sequenceNumber - b.sequenceNumber;
+          });
+          await observability.batchUpdateSpans({ records: sortedUpdates });
         }
-        if (span.errorInfo) {
-          this.logger.info(`   Error: ${formatAttributes(span.errorInfo)}`);
+      } else if (this.#resolvedStrategy === "insert-only") {
+        if (buffer.insertOnly.length > 0) {
+          await observability.batchCreateSpans({ records: buffer.insertOnly });
         }
-        this.logger.info(`   Attributes: ${formatAttributes(span.attributes)}`);
-        this.logger.info("\u2500".repeat(80));
+      }
+      for (const spanKey of buffer.completedSpans) {
+        this.allCreatedSpans.delete(spanKey);
+      }
+    } catch (error) {
+      if (attempt < this.#config.maxRetries) {
+        const retryDelay = this.calculateRetryDelay(attempt);
+        this.logger.warn("Batch flush failed, retrying", {
+          attempt: attempt + 1,
+          maxRetries: this.#config.maxRetries,
+          nextRetryInMs: retryDelay,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        return this.flushWithRetries(observability, buffer, attempt + 1);
+      } else {
+        this.logger.error("Batch flush failed after all retries, dropping batch", {
+          finalAttempt: attempt + 1,
+          maxRetries: this.#config.maxRetries,
+          droppedBatchSize: buffer.totalSize,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        for (const spanKey of buffer.completedSpans) {
+          this.allCreatedSpans.delete(spanKey);
+        }
+      }
+    }
+  }
+  async _exportTracingEvent(event) {
+    if (!this.#observability) {
+      this.logger.debug("Cannot store traces. Observability storage is not initialized");
+      return;
+    }
+    if (!this.#strategyInitialized) {
+      this.initializeStrategy(this.#observability, this.#storage?.constructor.name ?? "Unknown");
+    }
+    switch (this.#resolvedStrategy) {
+      case "realtime":
+        await this.handleRealtimeEvent(event, this.#observability);
+        break;
+      case "batch-with-updates":
+        this.handleBatchWithUpdatesEvent(event);
         break;
-      case observability.TracingEventType.SPAN_UPDATED:
-        this.logger.info(`\u{1F4DD} SPAN_UPDATED`);
-        this.logger.info(`   Type: ${span.type}`);
-        this.logger.info(`   Name: ${span.name}`);
-        this.logger.info(`   ID: ${span.id}`);
-        this.logger.info(`   Trace ID: ${span.traceId}`);
-        if (span.input !== void 0) {
-          this.logger.info(`   Input: ${formatAttributes(span.input)}`);
-        }
-        if (span.output !== void 0) {
-          this.logger.info(`   Output: ${formatAttributes(span.output)}`);
-        }
-        if (span.errorInfo) {
-          this.logger.info(`   Error: ${formatAttributes(span.errorInfo)}`);
-        }
-        this.logger.info(`   Updated Attributes: ${formatAttributes(span.attributes)}`);
-        this.logger.info("\u2500".repeat(80));
+      case "insert-only":
+        this.handleInsertOnlyEvent(event);
         break;
-      default:
-        this.logger.warn(`Tracing event type not implemented: ${event.type}`);
+    }
+  }
+  /**
+   * Force flush any buffered spans without shutting down the exporter.
+   * This is useful in serverless environments where you need to ensure spans
+   * are exported before the runtime instance is terminated.
+   */
+  async flush() {
+    if (this.buffer.totalSize > 0) {
+      this.logger.debug("Flushing buffered events", {
+        bufferedEvents: this.buffer.totalSize
+      });
+      await this.flushBuffer();
     }
   }
   async shutdown() {
-    this.logger.info("ConsoleExporter shutdown");
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+      this.#flushTimer = null;
+    }
+    await this.flush();
+    this.logger.info("DefaultExporter shutdown complete");
   }
 };
-function resolveTracingStorageStrategy(config, observability, storageName, logger) {
-  if (config.strategy && config.strategy !== "auto") {
-    const hints = observability.tracingStrategy;
-    if (hints.supported.includes(config.strategy)) {
-      return config.strategy;
-    }
-    logger.warn("User-specified tracing strategy not supported by storage adapter, falling back to auto-selection", {
-      userStrategy: config.strategy,
-      storageAdapter: storageName,
-      supportedStrategies: hints.supported,
-      fallbackStrategy: hints.preferred
-    });
+
+// src/exporters/test.ts
+var TestExporter = class extends BaseExporter {
+  name = "tracing-test-exporter";
+  #events = [];
+  constructor(config = {}) {
+    super(config);
   }
-  return observability.tracingStrategy.preferred;
-}
-function getStringOrNull(value) {
-  return typeof value === "string" ? value : null;
-}
-function getObjectOrNull(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-var DefaultExporter = class extends BaseExporter {
-  name = "mastra-default-observability-exporter";
-  #storage;
-  #observability;
+  async _exportTracingEvent(event) {
+    this.#events.push(event);
+  }
+  clearEvents() {
+    this.#events = [];
+  }
+  get events() {
+    return this.#events;
+  }
+  async shutdown() {
+    this.logger.info("TestExporter shutdown");
+  }
+};
+var __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+var __dirname$1 = path.dirname(__filename$1);
+var SNAPSHOTS_DIR = path.join(__dirname$1, "..", "__snapshots__");
+var JsonExporter = class extends BaseExporter {
+  name = "json-exporter";
+  /** All collected events */
+  #events = [];
+  /** Per-span state tracking */
+  #spanStates = /* @__PURE__ */ new Map();
+  /** Logs for debugging */
+  #logs = [];
+  /** Configuration */
   #config;
-  #resolvedStrategy;
-  buffer;
-  #flushTimer = null;
-  // Track all spans that have been created, persists across flushes
-  allCreatedSpans = /* @__PURE__ */ new Set();
   constructor(config = {}) {
     super(config);
-    if (config === void 0) {
-      config = {};
-    }
     this.#config = {
-      ...config,
-      maxBatchSize: config.maxBatchSize ?? 1e3,
-      maxBufferSize: config.maxBufferSize ?? 1e4,
-      maxBatchWaitMs: config.maxBatchWaitMs ?? 5e3,
-      maxRetries: config.maxRetries ?? 4,
-      retryDelayMs: config.retryDelayMs ?? 500,
-      strategy: config.strategy ?? "auto"
+      validateLifecycle: true,
+      storeLogs: true,
+      jsonIndent: 2,
+      ...config
     };
-    this.buffer = {
-      creates: [],
-      updates: [],
-      insertOnly: [],
-      seenSpans: /* @__PURE__ */ new Set(),
-      spanSequences: /* @__PURE__ */ new Map(),
-      completedSpans: /* @__PURE__ */ new Set(),
-      outOfOrderCount: 0,
-      totalSize: 0
-    };
-    this.#resolvedStrategy = "batch-with-updates";
   }
-  #strategyInitialized = false;
   /**
-   * Initialize the exporter (called after all dependencies are ready)
+   * Process incoming tracing events with lifecycle tracking
    */
-  async init(options) {
-    this.#storage = options.mastra?.getStorage();
-    if (!this.#storage) {
-      this.logger.warn("DefaultExporter disabled: Storage not available. Traces will not be persisted.");
-      return;
+  async _exportTracingEvent(event) {
+    const span = event.exportedSpan;
+    const spanId = span.id;
+    const logMessage = `[JsonExporter] ${event.type}: ${span.type} "${span.name}" (entity: ${span.entityName ?? span.entityId ?? "unknown"}, trace: ${span.traceId.slice(-8)}, span: ${spanId.slice(-8)})`;
+    if (this.#config.storeLogs) {
+      this.#logs.push(logMessage);
+    }
+    const state = this.#spanStates.get(spanId) || {
+      hasStart: false,
+      hasEnd: false,
+      hasUpdate: false,
+      events: []
+    };
+    if (this.#config.validateLifecycle) {
+      this.#validateLifecycle(event, state, spanId);
     }
-    this.#observability = await this.#storage.getStore("observability");
-    if (!this.#observability) {
-      this.logger.warn("DefaultExporter disabled: Observability storage not available. Traces will not be persisted.");
-      return;
+    if (event.type === observability.TracingEventType.SPAN_STARTED) {
+      state.hasStart = true;
+    } else if (event.type === observability.TracingEventType.SPAN_ENDED) {
+      state.hasEnd = true;
+      if (span.isEvent) {
+        state.isEventSpan = true;
+      }
+    } else if (event.type === observability.TracingEventType.SPAN_UPDATED) {
+      state.hasUpdate = true;
     }
-    this.initializeStrategy(this.#observability, this.#storage.constructor.name);
+    state.events.push(event);
+    this.#spanStates.set(spanId, state);
+    this.#events.push(event);
   }
   /**
-   * Initialize the resolved strategy once observability store is available
+   * Validate span lifecycle rules
    */
-  initializeStrategy(observability, storageName) {
-    if (this.#strategyInitialized) return;
-    this.#resolvedStrategy = resolveTracingStorageStrategy(this.#config, observability, storageName, this.logger);
-    this.#strategyInitialized = true;
-    this.logger.debug("tracing storage exporter initialized", {
-      strategy: this.#resolvedStrategy,
-      source: this.#config.strategy !== "auto" ? "user" : "auto",
-      storageAdapter: storageName,
-      maxBatchSize: this.#config.maxBatchSize,
-      maxBatchWaitMs: this.#config.maxBatchWaitMs
-    });
+  #validateLifecycle(event, state, spanId) {
+    const span = event.exportedSpan;
+    if (event.type === observability.TracingEventType.SPAN_STARTED) {
+      if (state.hasStart) {
+        this.logger.warn(`Span ${spanId} (${span.type} "${span.name}") started twice`);
+      }
+    } else if (event.type === observability.TracingEventType.SPAN_ENDED) {
+      if (span.isEvent) {
+        if (state.hasStart) {
+          this.logger.warn(`Event span ${spanId} (${span.type} "${span.name}") incorrectly received SPAN_STARTED`);
+        }
+        if (state.hasUpdate) {
+          this.logger.warn(`Event span ${spanId} (${span.type} "${span.name}") incorrectly received SPAN_UPDATED`);
+        }
+      } else {
+        if (!state.hasStart) {
+          this.logger.warn(`Normal span ${spanId} (${span.type} "${span.name}") ended without starting`);
+        }
+      }
+    }
   }
+  // ============================================================================
+  // Query Methods
+  // ============================================================================
   /**
-   * Builds a unique span key for tracking
+   * Get all collected events
    */
-  buildSpanKey(traceId, spanId) {
-    return `${traceId}:${spanId}`;
+  get events() {
+    return [...this.#events];
   }
   /**
-   * Gets the next sequence number for a span
+   * Get completed spans by SpanType (e.g., 'agent_run', 'tool_call')
+   *
+   * @param type - The SpanType to filter by
+   * @returns Array of completed exported spans of the specified type
    */
-  getNextSequence(spanKey) {
-    const current = this.buffer.spanSequences.get(spanKey) || 0;
-    const next = current + 1;
-    this.buffer.spanSequences.set(spanKey, next);
-    return next;
+  getSpansByType(type) {
+    return Array.from(this.#spanStates.values()).filter((state) => {
+      if (!state.hasEnd) return false;
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent?.exportedSpan.type === type;
+    }).map((state) => {
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent?.exportedSpan;
+    }).filter((span) => span !== void 0);
   }
   /**
-   * Handles out-of-order span updates by logging and skipping
+   * Get events by TracingEventType (SPAN_STARTED, SPAN_UPDATED, SPAN_ENDED)
+   *
+   * @param type - The TracingEventType to filter by
+   * @returns Array of events of the specified type
    */
-  handleOutOfOrderUpdate(event) {
-    this.logger.warn("Out-of-order span update detected - skipping event", {
-      spanId: event.exportedSpan.id,
-      traceId: event.exportedSpan.traceId,
-      spanName: event.exportedSpan.name,
-      eventType: event.type
-    });
+  getByEventType(type) {
+    return this.#events.filter((e) => e.type === type);
   }
   /**
-   * Adds an event to the appropriate buffer based on strategy
+   * Get all events and spans for a specific trace
+   *
+   * @param traceId - The trace ID to filter by
+   * @returns Object containing events and final spans for the trace
    */
-  addToBuffer(event) {
-    const spanKey = this.buildSpanKey(event.exportedSpan.traceId, event.exportedSpan.id);
-    if (this.buffer.totalSize === 0) {
-      this.buffer.firstEventTime = /* @__PURE__ */ new Date();
-    }
-    switch (event.type) {
-      case observability.TracingEventType.SPAN_STARTED:
-        if (this.#resolvedStrategy === "batch-with-updates") {
-          const createRecord = this.buildCreateRecord(event.exportedSpan);
-          this.buffer.creates.push(createRecord);
-          this.buffer.seenSpans.add(spanKey);
-          this.allCreatedSpans.add(spanKey);
-        }
-        break;
-      case observability.TracingEventType.SPAN_UPDATED:
-        if (this.#resolvedStrategy === "batch-with-updates") {
-          if (this.allCreatedSpans.has(spanKey)) {
-            this.buffer.updates.push({
-              traceId: event.exportedSpan.traceId,
-              spanId: event.exportedSpan.id,
-              updates: this.buildUpdateRecord(event.exportedSpan),
-              sequenceNumber: this.getNextSequence(spanKey)
-            });
-          } else {
-            this.handleOutOfOrderUpdate(event);
-            this.buffer.outOfOrderCount++;
-          }
-        }
-        break;
-      case observability.TracingEventType.SPAN_ENDED:
-        if (this.#resolvedStrategy === "batch-with-updates") {
-          if (this.allCreatedSpans.has(spanKey)) {
-            this.buffer.updates.push({
-              traceId: event.exportedSpan.traceId,
-              spanId: event.exportedSpan.id,
-              updates: this.buildUpdateRecord(event.exportedSpan),
-              sequenceNumber: this.getNextSequence(spanKey)
-            });
-            this.buffer.completedSpans.add(spanKey);
-          } else if (event.exportedSpan.isEvent) {
-            const createRecord = this.buildCreateRecord(event.exportedSpan);
-            this.buffer.creates.push(createRecord);
-            this.buffer.seenSpans.add(spanKey);
-            this.allCreatedSpans.add(spanKey);
-            this.buffer.completedSpans.add(spanKey);
-          } else {
-            this.handleOutOfOrderUpdate(event);
-            this.buffer.outOfOrderCount++;
-          }
-        } else if (this.#resolvedStrategy === "insert-only") {
-          const createRecord = this.buildCreateRecord(event.exportedSpan);
-          this.buffer.insertOnly.push(createRecord);
-          this.buffer.completedSpans.add(spanKey);
-          this.allCreatedSpans.add(spanKey);
-        }
-        break;
-    }
-    this.buffer.totalSize = this.buffer.creates.length + this.buffer.updates.length + this.buffer.insertOnly.length;
+  getByTraceId(traceId) {
+    const events = this.#events.filter((e) => e.exportedSpan.traceId === traceId);
+    const spans = this.#getUniqueSpansFromEvents(events);
+    return { events, spans };
   }
   /**
-   * Checks if buffer should be flushed based on size or time triggers
+   * Get all events for a specific span
+   *
+   * @param spanId - The span ID to filter by
+   * @returns Object containing events and final span state
    */
-  shouldFlush() {
-    if (this.buffer.totalSize >= this.#config.maxBufferSize) {
-      return true;
-    }
-    if (this.buffer.totalSize >= this.#config.maxBatchSize) {
-      return true;
+  getBySpanId(spanId) {
+    const state = this.#spanStates.get(spanId);
+    if (!state) {
+      return { events: [], span: void 0, state: void 0 };
     }
-    if (this.buffer.firstEventTime && this.buffer.totalSize > 0) {
-      const elapsed = Date.now() - this.buffer.firstEventTime.getTime();
-      if (elapsed >= this.#config.maxBatchWaitMs) {
-        return true;
+    const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+    const span = endEvent?.exportedSpan ?? state.events[state.events.length - 1]?.exportedSpan;
+    return { events: state.events, span, state };
+  }
+  /**
+   * Get all unique spans (returns the final state of each span)
+   */
+  getAllSpans() {
+    return Array.from(this.#spanStates.values()).map((state) => {
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent?.exportedSpan ?? state.events[state.events.length - 1]?.exportedSpan;
+    }).filter((span) => span !== void 0);
+  }
+  /**
+   * Get only completed spans (those that have received SPAN_ENDED)
+   */
+  getCompletedSpans() {
+    return Array.from(this.#spanStates.values()).filter((state) => state.hasEnd).map((state) => {
+      const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+      return endEvent.exportedSpan;
+    });
+  }
+  /**
+   * Get root spans only (spans with no parent)
+   */
+  getRootSpans() {
+    return this.getAllSpans().filter((span) => span.isRootSpan);
+  }
+  /**
+   * Get incomplete spans (started but not yet ended)
+   */
+  getIncompleteSpans() {
+    return Array.from(this.#spanStates.entries()).filter(([_, state]) => !state.hasEnd).map(([spanId, state]) => ({
+      spanId,
+      span: state.events[0]?.exportedSpan,
+      state: {
+        hasStart: state.hasStart,
+        hasUpdate: state.hasUpdate,
+        hasEnd: state.hasEnd
       }
-    }
-    return false;
+    }));
   }
   /**
-   * Resets the buffer after successful flush
+   * Get unique trace IDs from all collected spans
    */
-  resetBuffer(completedSpansToCleanup = /* @__PURE__ */ new Set()) {
-    this.buffer.creates = [];
-    this.buffer.updates = [];
-    this.buffer.insertOnly = [];
-    this.buffer.seenSpans.clear();
-    this.buffer.spanSequences.clear();
-    this.buffer.completedSpans.clear();
-    this.buffer.outOfOrderCount = 0;
-    this.buffer.firstEventTime = void 0;
-    this.buffer.totalSize = 0;
-    for (const spanKey of completedSpansToCleanup) {
-      this.allCreatedSpans.delete(spanKey);
+  getTraceIds() {
+    const traceIds = /* @__PURE__ */ new Set();
+    for (const event of this.#events) {
+      traceIds.add(event.exportedSpan.traceId);
     }
+    return Array.from(traceIds);
   }
+  // ============================================================================
+  // Statistics
+  // ============================================================================
   /**
-   * Schedules a flush using setTimeout
+   * Get comprehensive statistics about collected spans
    */
-  scheduleFlush() {
-    if (this.#flushTimer) {
-      clearTimeout(this.#flushTimer);
+  getStatistics() {
+    const bySpanType = {};
+    let completedSpans = 0;
+    let incompleteSpans = 0;
+    for (const state of this.#spanStates.values()) {
+      if (state.hasEnd) {
+        completedSpans++;
+        const endEvent = state.events.find((e) => e.type === observability.TracingEventType.SPAN_ENDED);
+        const spanType = endEvent?.exportedSpan.type;
+        if (spanType) {
+          bySpanType[spanType] = (bySpanType[spanType] || 0) + 1;
+        }
+      } else {
+        incompleteSpans++;
+      }
     }
-    this.#flushTimer = setTimeout(() => {
-      this.flush().catch((error) => {
-        this.logger.error("Scheduled flush failed", {
-          error: error instanceof Error ? error.message : String(error)
-        });
-      });
-    }, this.#config.maxBatchWaitMs);
+    return {
+      totalEvents: this.#events.length,
+      totalSpans: this.#spanStates.size,
+      totalTraces: this.getTraceIds().length,
+      completedSpans,
+      incompleteSpans,
+      byEventType: {
+        started: this.#events.filter((e) => e.type === observability.TracingEventType.SPAN_STARTED).length,
+        updated: this.#events.filter((e) => e.type === observability.TracingEventType.SPAN_UPDATED).length,
+        ended: this.#events.filter((e) => e.type === observability.TracingEventType.SPAN_ENDED).length
+      },
+      bySpanType
+    };
   }
+  // ============================================================================
+  // JSON Output
+  // ============================================================================
   /**
-   * Serializes span attributes to storage record format
-   * Handles all Span types and their specific attributes
+   * Serialize all collected data to JSON string
+   *
+   * @param options - Serialization options
+   * @returns JSON string of all collected data
    */
-  serializeAttributes(span) {
-    if (!span.attributes) {
-      return null;
+  toJSON(options) {
+    const indent = options?.indent ?? this.#config.jsonIndent;
+    const includeEvents = options?.includeEvents ?? true;
+    const includeStats = options?.includeStats ?? true;
+    const data = {
+      spans: this.getAllSpans()
+    };
+    if (includeEvents) {
+      data.events = this.#events;
     }
-    try {
-      return JSON.parse(
-        JSON.stringify(span.attributes, (_key, value) => {
-          if (value instanceof Date) {
-            return value.toISOString();
-          }
-          if (typeof value === "object" && value !== null) {
-            return value;
-          }
-          return value;
-        })
-      );
-    } catch (error) {
-      this.logger.warn("Failed to serialize span attributes, storing as null", {
-        spanId: span.id,
-        spanType: span.type,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      return null;
+    if (includeStats) {
+      data.statistics = this.getStatistics();
     }
+    return JSON.stringify(data, this.#jsonReplacer, indent);
   }
-  buildCreateRecord(span) {
-    const metadata = span.metadata ?? {};
-    return {
-      traceId: span.traceId,
-      spanId: span.id,
-      parentSpanId: span.parentSpanId ?? null,
-      name: span.name,
-      // Entity identification - from span
-      entityType: span.entityType ?? null,
-      entityId: span.entityId ?? null,
-      entityName: span.entityName ?? null,
-      // Identity & Tenancy - extracted from metadata if present
-      userId: getStringOrNull(metadata.userId),
-      organizationId: getStringOrNull(metadata.organizationId),
-      resourceId: getStringOrNull(metadata.resourceId),
-      // Correlation IDs - extracted from metadata if present
-      runId: getStringOrNull(metadata.runId),
-      sessionId: getStringOrNull(metadata.sessionId),
-      threadId: getStringOrNull(metadata.threadId),
-      requestId: getStringOrNull(metadata.requestId),
-      // Deployment context - extracted from metadata if present
-      environment: getStringOrNull(metadata.environment),
-      source: getStringOrNull(metadata.source),
-      serviceName: getStringOrNull(metadata.serviceName),
-      scope: getObjectOrNull(metadata.scope),
-      // Span data
-      spanType: span.type,
-      attributes: this.serializeAttributes(span),
-      metadata: span.metadata ?? null,
-      // Keep all metadata including extracted fields
-      tags: span.tags ?? null,
-      links: null,
-      input: span.input ?? null,
-      output: span.output ?? null,
-      error: span.errorInfo ?? null,
-      isEvent: span.isEvent,
-      // Timestamps
-      startedAt: span.startTime,
-      endedAt: span.endTime ?? null
+  /**
+   * Build a tree structure from spans, nesting children under their parents
+   *
+   * @returns Array of root span tree nodes (spans with no parent)
+   */
+  buildSpanTree() {
+    const spans = this.getAllSpans();
+    const nodeMap = /* @__PURE__ */ new Map();
+    const roots = [];
+    for (const span of spans) {
+      nodeMap.set(span.id, { span, children: [] });
+    }
+    for (const span of spans) {
+      const node = nodeMap.get(span.id);
+      if (span.parentSpanId && nodeMap.has(span.parentSpanId)) {
+        nodeMap.get(span.parentSpanId).children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+    const sortChildren = (node) => {
+      node.children.sort((a, b) => new Date(a.span.startTime).getTime() - new Date(b.span.startTime).getTime());
+      node.children.forEach(sortChildren);
     };
+    roots.forEach(sortChildren);
+    return roots;
   }
-  buildUpdateRecord(span) {
-    return {
-      name: span.name,
-      scope: null,
-      attributes: this.serializeAttributes(span),
-      metadata: span.metadata ?? null,
-      links: null,
-      endedAt: span.endTime ?? null,
-      input: span.input,
-      output: span.output,
-      error: span.errorInfo ?? null
+  /**
+   * Serialize spans as a tree structure to JSON string
+   *
+   * @param options - Serialization options
+   * @returns JSON string with spans nested in tree format
+   */
+  toTreeJSON(options) {
+    const indent = options?.indent ?? this.#config.jsonIndent;
+    const includeStats = options?.includeStats ?? true;
+    const data = {
+      tree: this.buildSpanTree()
     };
+    if (includeStats) {
+      data.statistics = this.getStatistics();
+    }
+    return JSON.stringify(data, this.#jsonReplacer, indent);
   }
   /**
-   * Handles realtime strategy - processes each event immediately
+   * Build a normalized tree structure suitable for snapshot testing.
+   *
+   * Normalizations applied:
+   * - Span IDs replaced with stable placeholders (<span-1>, <span-2>, etc.)
+   * - Trace IDs replaced with stable placeholders (<trace-1>, <trace-2>, etc.)
+   * - parentSpanId replaced with normalized parent ID
+   * - Timestamps replaced with durationMs (or null if not ended)
+   * - Empty children arrays are omitted
+   *
+   * @returns Array of normalized root tree nodes
    */
-  async handleRealtimeEvent(event, observability$1) {
-    const span = event.exportedSpan;
-    const spanKey = this.buildSpanKey(span.traceId, span.id);
-    if (span.isEvent) {
-      if (event.type === observability.TracingEventType.SPAN_ENDED) {
-        await observability$1.createSpan({ span: this.buildCreateRecord(event.exportedSpan) });
-      } else {
-        this.logger.warn(`Tracing event type not implemented for event spans: ${event.type}`);
+  buildNormalizedTree() {
+    const tree = this.buildSpanTree();
+    const spanIdMap = /* @__PURE__ */ new Map();
+    const traceIdMap = /* @__PURE__ */ new Map();
+    const uuidMapsByKey = /* @__PURE__ */ new Map();
+    const uuidCountersByKey = /* @__PURE__ */ new Map();
+    let spanIdCounter = 1;
+    let traceIdCounter = 1;
+    const uuidRegex2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const hexId32Regex = /^[0-9a-f]{32}$/i;
+    const prefixedUuidRegex = /^([a-z_]+)_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+    const embeddedPrefixedUuidRegex = /([a-z_]+)_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi;
+    const normalizeUuid = (uuid, key) => {
+      if (!uuidMapsByKey.has(key)) {
+        uuidMapsByKey.set(key, /* @__PURE__ */ new Map());
+        uuidCountersByKey.set(key, 1);
       }
-    } else {
-      switch (event.type) {
-        case observability.TracingEventType.SPAN_STARTED:
-          await observability$1.createSpan({ span: this.buildCreateRecord(event.exportedSpan) });
-          this.allCreatedSpans.add(spanKey);
-          break;
-        case observability.TracingEventType.SPAN_UPDATED:
-          await observability$1.updateSpan({
-            traceId: span.traceId,
-            spanId: span.id,
-            updates: this.buildUpdateRecord(span)
-          });
-          break;
-        case observability.TracingEventType.SPAN_ENDED:
-          await observability$1.updateSpan({
-            traceId: span.traceId,
-            spanId: span.id,
-            updates: this.buildUpdateRecord(span)
+      const keyMap = uuidMapsByKey.get(key);
+      if (!keyMap.has(uuid)) {
+        const counter = uuidCountersByKey.get(key);
+        keyMap.set(uuid, `<${key}-${counter}>`);
+        uuidCountersByKey.set(key, counter + 1);
+      }
+      return keyMap.get(uuid);
+    };
+    const normalizeValue = (value, key) => {
+      if (value instanceof Date) {
+        return "<date>";
+      }
+      if (typeof value === "string") {
+        if (key === "traceId" && (uuidRegex2.test(value) || hexId32Regex.test(value))) {
+          if (!traceIdMap.has(value)) {
+            traceIdMap.set(value, `<trace-${traceIdCounter++}>`);
+          }
+          return traceIdMap.get(value);
+        }
+        if (uuidRegex2.test(value)) {
+          return normalizeUuid(value, key ?? "uuid");
+        }
+        const prefixMatch = prefixedUuidRegex.exec(value);
+        if (prefixMatch && prefixMatch[1] && prefixMatch[2]) {
+          const prefix = prefixMatch[1];
+          const uuid = prefixMatch[2];
+          return `${prefix}_${normalizeUuid(uuid, prefix)}`;
+        }
+        if (embeddedPrefixedUuidRegex.test(value)) {
+          embeddedPrefixedUuidRegex.lastIndex = 0;
+          return value.replace(embeddedPrefixedUuidRegex, (_match, prefix, uuid) => {
+            return `${prefix}_${normalizeUuid(uuid, prefix)}`;
           });
-          this.allCreatedSpans.delete(spanKey);
-          break;
-        default:
-          this.logger.warn(`Tracing event type not implemented for span spans: ${event.type}`);
+        }
       }
-    }
+      if (Array.isArray(value)) {
+        return value.map((v) => normalizeValue(v, key));
+      }
+      if (value && typeof value === "object") {
+        const normalized = {};
+        for (const [k, v] of Object.entries(value)) {
+          normalized[k] = normalizeValue(v, k);
+        }
+        return normalized;
+      }
+      return value;
+    };
+    const assignIds = (nodes) => {
+      for (const node of nodes) {
+        spanIdMap.set(node.span.id, `<span-${spanIdCounter++}>`);
+        if (!traceIdMap.has(node.span.traceId)) {
+          traceIdMap.set(node.span.traceId, `<trace-${traceIdCounter++}>`);
+        }
+        assignIds(node.children);
+      }
+    };
+    assignIds(tree);
+    const normalizeNode = (node) => {
+      const span = node.span;
+      const completed = span.endTime !== void 0 && span.endTime !== null;
+      const normalizedSpan = {
+        id: spanIdMap.get(span.id),
+        traceId: traceIdMap.get(span.traceId),
+        name: normalizeValue(span.name, "name"),
+        type: span.type,
+        completed,
+        isEvent: span.isEvent,
+        isRootSpan: span.isRootSpan
+      };
+      if (span.parentSpanId && spanIdMap.has(span.parentSpanId)) {
+        normalizedSpan.parentId = spanIdMap.get(span.parentSpanId);
+      }
+      if (span.entityType) {
+        normalizedSpan.entityType = span.entityType;
+      }
+      if (span.entityId) {
+        normalizedSpan.entityId = normalizeValue(span.entityId, "entityId");
+      }
+      if (span.attributes && Object.keys(span.attributes).length > 0) {
+        normalizedSpan.attributes = normalizeValue(span.attributes);
+      }
+      if (span.metadata && Object.keys(span.metadata).length > 0) {
+        normalizedSpan.metadata = normalizeValue(span.metadata);
+      }
+      if (span.input !== void 0) {
+        normalizedSpan.input = normalizeValue(span.input);
+      }
+      if (span.output !== void 0) {
+        normalizedSpan.output = normalizeValue(span.output);
+      }
+      if (span.errorInfo) {
+        normalizedSpan.errorInfo = span.errorInfo;
+      }
+      if (span.tags && span.tags.length > 0) {
+        normalizedSpan.tags = span.tags;
+      }
+      const result = { span: normalizedSpan };
+      if (node.children.length > 0) {
+        result.children = node.children.map(normalizeNode);
+      }
+      return result;
+    };
+    return tree.map(normalizeNode);
   }
   /**
-   * Handles batch-with-updates strategy - buffers events and processes in batches
+   * Generate an ASCII tree structure graph for debugging.
+   * Shows span type and name in a hierarchical format.
+   *
+   * @param nodes - Normalized tree nodes (defaults to current normalized tree)
+   * @returns Array of strings representing the tree structure
+   *
+   * @example
+   * ```
+   * agent_run: "agent run: 'test-agent'"
+   * ├── processor_run: "input processor: validator"
+   * │   └── agent_run: "agent run: 'validator-agent'"
+   * └── model_generation: "llm: 'mock-model-id'"
+   * ```
    */
-  handleBatchWithUpdatesEvent(event) {
-    this.addToBuffer(event);
-    if (this.shouldFlush()) {
-      this.flush().catch((error) => {
-        this.logger.error("Batch flush failed", {
-          error: error instanceof Error ? error.message : String(error)
-        });
+  generateStructureGraph(nodes) {
+    const tree = nodes ?? this.buildNormalizedTree();
+    const lines = [];
+    const buildLines = (node, prefix, isLast, isRoot) => {
+      const connector = isRoot ? "" : isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+      const line = `${prefix}${connector}${node.span.type}: "${node.span.name}"`;
+      lines.push(line);
+      const children = node.children ?? [];
+      const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "\u2502   ");
+      children.forEach((child, index) => {
+        const childIsLast = index === children.length - 1;
+        buildLines(child, childPrefix, childIsLast, false);
       });
-    } else if (this.buffer.totalSize === 1) {
-      this.scheduleFlush();
-    }
+    };
+    tree.forEach((rootNode, index) => {
+      if (index > 0) {
+        lines.push("");
+      }
+      buildLines(rootNode, "", true, true);
+    });
+    return lines;
   }
   /**
-   * Handles insert-only strategy - only processes SPAN_ENDED events in batches
+   * Serialize spans as a normalized tree structure for snapshot testing.
+   * Includes a __structure__ field with an ASCII tree graph for readability.
+   *
+   * @param options - Serialization options
+   * @returns JSON string with normalized spans in tree format
    */
-  handleInsertOnlyEvent(event) {
-    if (event.type === observability.TracingEventType.SPAN_ENDED) {
-      this.addToBuffer(event);
-      if (this.shouldFlush()) {
-        this.flush().catch((error) => {
-          this.logger.error("Batch flush failed", {
-            error: error instanceof Error ? error.message : String(error)
-          });
-        });
-      } else if (this.buffer.totalSize === 1) {
-        this.scheduleFlush();
-      }
+  toNormalizedTreeJSON(options) {
+    const indent = options?.indent ?? this.#config.jsonIndent;
+    const includeStructure = options?.includeStructure ?? true;
+    const normalizedTree = this.buildNormalizedTree();
+    if (includeStructure) {
+      const structureGraph = this.generateStructureGraph(normalizedTree);
+      const data = {
+        __structure__: structureGraph,
+        spans: normalizedTree
+      };
+      return JSON.stringify(data, null, indent);
     }
+    return JSON.stringify(normalizedTree, null, indent);
   }
   /**
-   * Calculates retry delay using exponential backoff
+   * Write collected data to a JSON file
+   *
+   * @param filePath - Path to write the JSON file
+   * @param options - Serialization options
    */
-  calculateRetryDelay(attempt) {
-    return this.#config.retryDelayMs * Math.pow(2, attempt);
+  async writeToFile(filePath, options) {
+    const format = options?.format ?? "flat";
+    let json;
+    if (format === "normalized") {
+      json = this.toNormalizedTreeJSON({ indent: options?.indent });
+    } else if (format === "tree") {
+      json = this.toTreeJSON({ indent: options?.indent, includeStats: options?.includeStats });
+    } else {
+      json = this.toJSON(options);
+    }
+    await promises.writeFile(filePath, json, "utf-8");
+    this.logger.info(`JsonExporter: wrote ${this.#events.length} events to ${filePath}`);
   }
   /**
-   * Flushes the current buffer to storage with retry logic
+   * Assert that the current normalized tree matches a snapshot file.
+   * Throws an error with a diff if they don't match.
+   *
+   * The snapshot format includes:
+   * - `__structure__`: ASCII tree graph (compared first for quick validation)
+   * - `spans`: The normalized span tree (detailed comparison)
+   *
+   * Supports special markers in the snapshot:
+   * - `{"__or__": ["value1", "value2"]}` - matches if actual equals any listed value
+   * - `{"__any__": "string"}` - matches any string value
+   * - `{"__any__": "number"}` - matches any number value
+   * - `{"__any__": "boolean"}` - matches any boolean value
+   * - `{"__any__": "object"}` - matches any object value
+   * - `{"__any__": "array"}` - matches any array value
+   * - `{"__any__": true}` - matches any non-null/undefined value
+   *
+   * Environment variables:
+   * Use `{ updateSnapshot: true }` option to update the snapshot instead of comparing
+   *
+   * @param snapshotName - Name of the snapshot file (resolved relative to __snapshots__ directory)
+   * @param options - Options for snapshot comparison
+   * @param options.updateSnapshot - If true, update the snapshot file instead of comparing
+   * @throws Error if the snapshot doesn't match (and updateSnapshot is false)
    */
-  async flush() {
-    if (!this.#observability) {
-      this.logger.debug("Cannot flush traces. Observability storage is not initialized");
-      return;
-    }
-    if (this.#flushTimer) {
-      clearTimeout(this.#flushTimer);
-      this.#flushTimer = null;
-    }
-    if (this.buffer.totalSize === 0) {
+  async assertMatchesSnapshot(snapshotName, options) {
+    const snapshotPath = path.join(SNAPSHOTS_DIR, snapshotName);
+    const normalizedTree = this.buildNormalizedTree();
+    const structureGraph = this.generateStructureGraph(normalizedTree);
+    const currentData = {
+      __structure__: structureGraph,
+      spans: normalizedTree
+    };
+    const currentJson = JSON.stringify(currentData, null, this.#config.jsonIndent);
+    const shouldUpdate = options?.updateSnapshot;
+    if (shouldUpdate) {
+      await promises.writeFile(snapshotPath, currentJson, "utf-8");
+      this.logger.info(`JsonExporter: updated snapshot ${snapshotPath}`);
       return;
     }
-    const startTime = Date.now();
-    const flushReason = this.buffer.totalSize >= this.#config.maxBufferSize ? "overflow" : this.buffer.totalSize >= this.#config.maxBatchSize ? "size" : "time";
-    const bufferCopy = {
-      creates: [...this.buffer.creates],
-      updates: [...this.buffer.updates],
-      insertOnly: [...this.buffer.insertOnly],
-      seenSpans: new Set(this.buffer.seenSpans),
-      spanSequences: new Map(this.buffer.spanSequences),
-      completedSpans: new Set(this.buffer.completedSpans),
-      outOfOrderCount: this.buffer.outOfOrderCount,
-      firstEventTime: this.buffer.firstEventTime,
-      totalSize: this.buffer.totalSize
-    };
-    this.resetBuffer();
-    await this.flushWithRetries(this.#observability, bufferCopy, 0);
-    const elapsed = Date.now() - startTime;
-    this.logger.debug("Batch flushed", {
-      strategy: this.#resolvedStrategy,
-      batchSize: bufferCopy.totalSize,
-      flushReason,
-      durationMs: elapsed,
-      outOfOrderCount: bufferCopy.outOfOrderCount > 0 ? bufferCopy.outOfOrderCount : void 0
-    });
+    let snapshotData;
+    try {
+      const snapshotContent = await promises.readFile(snapshotPath, "utf-8");
+      snapshotData = JSON.parse(snapshotContent);
+    } catch {
+      throw new Error(`Snapshot file not found: ${snapshotPath}
+Run with { updateSnapshot: true } to create it.`);
+    }
+    let expectedSpans;
+    let expectedStructure;
+    if (Array.isArray(snapshotData)) {
+      expectedSpans = snapshotData;
+    } else if (snapshotData && typeof snapshotData === "object" && "spans" in snapshotData) {
+      expectedSpans = snapshotData.spans;
+      expectedStructure = snapshotData.__structure__;
+    } else {
+      throw new Error(
+        `Invalid snapshot format in ${snapshotPath}.
+Expected an array or object with 'spans' property.`
+      );
+    }
+    if (expectedStructure) {
+      const structureMismatches = this.#compareStructure(structureGraph, expectedStructure);
+      if (structureMismatches.length > 0) {
+        throw new Error(
+          `Structure mismatch in snapshot:
+
+Expected:
+${expectedStructure.join("\n")}
+
+Actual:
+${structureGraph.join("\n")}
+
+Differences:
+${structureMismatches.join("\n")}
+
+Snapshot: ${snapshotPath}
+Run with { updateSnapshot: true } to update.`
+        );
+      }
+    }
+    const mismatches = [];
+    this.#deepCompareWithMarkers(normalizedTree, expectedSpans, "$.spans", mismatches);
+    if (mismatches.length > 0) {
+      const mismatchDetails = mismatches.map(
+        (m, i) => `${i + 1}. ${m.path}
+   Expected: ${JSON.stringify(m.expected)}
+   Actual:   ${JSON.stringify(m.actual)}`
+      ).join("\n\n");
+      throw new Error(
+        `Snapshot has ${mismatches.length} mismatch${mismatches.length > 1 ? "es" : ""}:
+
+${mismatchDetails}
+
+Snapshot: ${snapshotPath}
+Run with { updateSnapshot: true } to update.`
+      );
+    }
   }
   /**
-   * Attempts to flush with exponential backoff retry logic
+   * Compare two structure graphs and return differences
    */
-  async flushWithRetries(observability, buffer, attempt) {
-    try {
-      if (this.#resolvedStrategy === "batch-with-updates") {
-        if (buffer.creates.length > 0) {
-          await observability.batchCreateSpans({ records: buffer.creates });
-        }
-        if (buffer.updates.length > 0) {
-          const sortedUpdates = buffer.updates.sort((a, b) => {
-            const spanCompare = this.buildSpanKey(a.traceId, a.spanId).localeCompare(
-              this.buildSpanKey(b.traceId, b.spanId)
-            );
-            if (spanCompare !== 0) return spanCompare;
-            return a.sequenceNumber - b.sequenceNumber;
-          });
-          await observability.batchUpdateSpans({ records: sortedUpdates });
-        }
-      } else if (this.#resolvedStrategy === "insert-only") {
-        if (buffer.insertOnly.length > 0) {
-          await observability.batchCreateSpans({ records: buffer.insertOnly });
+  #compareStructure(actual, expected) {
+    const diffs = [];
+    const maxLen = Math.max(actual.length, expected.length);
+    for (let i = 0; i < maxLen; i++) {
+      const actualLine = actual[i];
+      const expectedLine = expected[i];
+      if (actualLine !== expectedLine) {
+        if (actualLine === void 0) {
+          diffs.push(`Line ${i + 1}: Missing in actual`);
+          diffs.push(`  Expected: ${expectedLine}`);
+        } else if (expectedLine === void 0) {
+          diffs.push(`Line ${i + 1}: Extra in actual`);
+          diffs.push(`  Actual: ${actualLine}`);
+        } else {
+          diffs.push(`Line ${i + 1}:`);
+          diffs.push(`  Expected: ${expectedLine}`);
+          diffs.push(`  Actual:   ${actualLine}`);
         }
       }
-      for (const spanKey of buffer.completedSpans) {
-        this.allCreatedSpans.delete(spanKey);
+    }
+    return diffs;
+  }
+  /**
+   * Deep compare two values, supporting special markers like __or__ and __any__.
+   * Collects all mismatches into the provided array.
+   */
+  #deepCompareWithMarkers(actual, expected, path, mismatches) {
+    if (this.#isOrMarker(expected)) {
+      const allowedValues = expected.__or__;
+      const matches = allowedValues.some((allowed) => {
+        const tempMismatches = [];
+        this.#deepCompareWithMarkers(actual, allowed, path, tempMismatches);
+        return tempMismatches.length === 0;
+      });
+      if (!matches) {
+        mismatches.push({ path, expected: { __or__: allowedValues }, actual });
       }
-    } catch (error) {
-      if (attempt < this.#config.maxRetries) {
-        const retryDelay = this.calculateRetryDelay(attempt);
-        this.logger.warn("Batch flush failed, retrying", {
-          attempt: attempt + 1,
-          maxRetries: this.#config.maxRetries,
-          nextRetryInMs: retryDelay,
-          error: error instanceof Error ? error.message : String(error)
-        });
-        await new Promise((resolve) => setTimeout(resolve, retryDelay));
-        return this.flushWithRetries(observability, buffer, attempt + 1);
-      } else {
-        this.logger.error("Batch flush failed after all retries, dropping batch", {
-          finalAttempt: attempt + 1,
-          maxRetries: this.#config.maxRetries,
-          droppedBatchSize: buffer.totalSize,
-          error: error instanceof Error ? error.message : String(error)
+      return;
+    }
+    if (this.#isAnyMarker(expected)) {
+      const typeConstraint = expected.__any__;
+      if (actual === null || actual === void 0) {
+        mismatches.push({ path, expected: { __any__: typeConstraint }, actual });
+        return;
+      }
+      if (typeConstraint === true) {
+        return;
+      }
+      const actualType = Array.isArray(actual) ? "array" : typeof actual;
+      if (actualType !== typeConstraint) {
+        mismatches.push({
+          path,
+          expected: { __any__: typeConstraint },
+          actual: `(${actualType}) ${JSON.stringify(actual).slice(0, 50)}...`
         });
-        for (const spanKey of buffer.completedSpans) {
-          this.allCreatedSpans.delete(spanKey);
-        }
       }
+      return;
     }
-  }
-  async _exportTracingEvent(event) {
-    if (!this.#observability) {
-      this.logger.debug("Cannot store traces. Observability storage is not initialized");
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(actual)) {
+        mismatches.push({ path, expected, actual });
+        return;
+      }
+      if (actual.length !== expected.length) {
+        mismatches.push({ path: `${path}.length`, expected: expected.length, actual: actual.length });
+        return;
+      }
+      for (let i = 0; i < expected.length; i++) {
+        this.#deepCompareWithMarkers(actual[i], expected[i], `${path}[${i}]`, mismatches);
+      }
       return;
     }
-    if (!this.#strategyInitialized) {
-      this.initializeStrategy(this.#observability, this.#storage?.constructor.name ?? "Unknown");
+    if (expected !== null && typeof expected === "object") {
+      if (actual === null || typeof actual !== "object" || Array.isArray(actual)) {
+        mismatches.push({ path, expected, actual });
+        return;
+      }
+      const expectedObj = expected;
+      const actualObj = actual;
+      for (const key of Object.keys(expectedObj)) {
+        if (this.#isMetadataKey(key)) {
+          continue;
+        }
+        if (!(key in actualObj)) {
+          if (expectedObj[key] !== void 0) {
+            mismatches.push({ path: `${path}.${key}`, expected: expectedObj[key], actual: void 0 });
+          }
+          continue;
+        }
+        this.#deepCompareWithMarkers(actualObj[key], expectedObj[key], `${path}.${key}`, mismatches);
+      }
+      for (const key of Object.keys(actualObj)) {
+        if (this.#isMetadataKey(key)) {
+          continue;
+        }
+        if (!(key in expectedObj)) {
+          if (actualObj[key] !== void 0) {
+            mismatches.push({ path: `${path}.${key}`, expected: void 0, actual: actualObj[key] });
+          }
+        }
+      }
+      return;
     }
-    switch (this.#resolvedStrategy) {
-      case "realtime":
-        await this.handleRealtimeEvent(event, this.#observability);
-        break;
-      case "batch-with-updates":
-        this.handleBatchWithUpdatesEvent(event);
-        break;
-      case "insert-only":
-        this.handleInsertOnlyEvent(event);
-        break;
+    if (actual !== expected) {
+      mismatches.push({ path, expected, actual });
     }
   }
-  async shutdown() {
-    if (this.#flushTimer) {
-      clearTimeout(this.#flushTimer);
-      this.#flushTimer = null;
+  /**
+   * Check if a value is an __or__ marker object
+   */
+  #isOrMarker(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) && "__or__" in value && Array.isArray(value.__or__);
+  }
+  /**
+   * Check if a value is an __any__ marker object
+   */
+  #isAnyMarker(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return false;
     }
-    if (this.buffer.totalSize > 0) {
-      this.logger.info("Flushing remaining events on shutdown", {
-        remainingEvents: this.buffer.totalSize
-      });
-      try {
-        await this.flush();
-      } catch (error) {
-        this.logger.error("Failed to flush remaining events during shutdown", {
-          error: error instanceof Error ? error.message : String(error)
-        });
-      }
+    if (!("__any__" in value)) {
+      return false;
     }
-    this.logger.info("DefaultExporter shutdown complete");
+    const constraint = value.__any__;
+    return constraint === true || ["string", "number", "boolean", "object", "array"].includes(constraint);
   }
-};
-
-// src/exporters/test.ts
-var TestExporter = class extends BaseExporter {
-  name = "tracing-test-exporter";
-  #events = [];
-  constructor(config = {}) {
-    super(config);
+  /**
+   * Check if a key should be skipped during comparison (metadata keys like __structure__)
+   */
+  #isMetadataKey(key) {
+    return key.startsWith("__") && key.endsWith("__");
   }
-  async _exportTracingEvent(event) {
-    this.#events.push(event);
+  /**
+   * Custom JSON replacer to handle Date objects and other special types
+   */
+  #jsonReplacer = (_key, value) => {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    return value;
+  };
+  // ============================================================================
+  // Debugging Helpers
+  // ============================================================================
+  /**
+   * Get all stored logs
+   */
+  getLogs() {
+    return [...this.#logs];
+  }
+  /**
+   * Dump logs to console for debugging (uses console.error for visibility in test output)
+   */
+  dumpLogs() {
+    console.error("\n=== JsonExporter Logs ===");
+    this.#logs.forEach((log) => console.error(log));
+    console.error("=== End Logs ===\n");
+  }
+  /**
+   * Validate final state - useful for test assertions
+   *
+   * @returns Object with validation results
+   */
+  validateFinalState() {
+    const traceIds = this.getTraceIds();
+    const incompleteSpans = this.getIncompleteSpans();
+    const singleTraceId = traceIds.length === 1;
+    const allSpansComplete = incompleteSpans.length === 0;
+    return {
+      valid: singleTraceId && allSpansComplete,
+      singleTraceId,
+      allSpansComplete,
+      traceIds,
+      incompleteSpans
+    };
   }
+  // ============================================================================
+  // Reset & Lifecycle
+  // ============================================================================
+  /**
+   * Clear all collected events and state
+   */
   clearEvents() {
     this.#events = [];
+    this.#spanStates.clear();
+    this.#logs = [];
   }
-  get events() {
-    return this.#events;
+  /**
+   * Alias for clearEvents (compatibility with TestExporter)
+   */
+  reset() {
+    this.clearEvents();
   }
   async shutdown() {
-    this.logger.info("TestExporter shutdown");
+    this.logger.info("JsonExporter shutdown");
+  }
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+  /**
+   * Extract unique spans from a list of events
+   */
+  #getUniqueSpansFromEvents(events) {
+    const spanMap = /* @__PURE__ */ new Map();
+    for (const event of events) {
+      const span = event.exportedSpan;
+      if (event.type === observability.TracingEventType.SPAN_ENDED || !spanMap.has(span.id)) {
+        spanMap.set(span.id, span);
+      }
+    }
+    return Array.from(spanMap.values());
   }
 };
 
@@ -5082,14 +6941,11 @@ var ModelSpanTracker = class {
   #modelSpan;
   #currentStepSpan;
   #currentChunkSpan;
+  #currentChunkType;
   #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;
   }
@@ -5176,6 +7032,7 @@ var ModelSpanTracker = class {
    * End the current Model execution step with token usage, finish reason, output, and metadata
    */
   #endStepSpan(payload) {
+    this.#endChunkSpan();
     if (!this.#currentStepSpan) return;
     const output = payload.output;
     const { usage: rawUsage, ...otherOutput } = output;
@@ -5183,8 +7040,10 @@ var ModelSpanTracker = class {
     const metadata = payload.metadata;
     const usage = extractUsageMetrics(rawUsage, metadata?.providerMetadata);
     const cleanMetadata = metadata ? { ...metadata } : void 0;
-    if (cleanMetadata?.request) {
-      delete cleanMetadata.request;
+    if (cleanMetadata) {
+      for (const key of ["request", "id", "timestamp", "modelId", "modelVersion", "modelProvider"]) {
+        delete cleanMetadata[key];
+      }
     }
     this.#currentStepSpan.end({
       output: otherOutput,
@@ -5205,6 +7064,7 @@ var ModelSpanTracker = class {
    * Create a new chunk span (for multi-part chunks like text-start/delta/end)
    */
   #startChunkSpan(chunkType, initialData) {
+    this.#endChunkSpan();
     if (!this.#currentStepSpan) {
       this.startStep();
     }
@@ -5216,6 +7076,7 @@ var ModelSpanTracker = class {
         sequenceNumber: this.#chunkSequence
       }
     });
+    this.#currentChunkType = chunkType;
     this.#accumulator = initialData || {};
   }
   /**
@@ -5238,13 +7099,14 @@ var ModelSpanTracker = class {
       output: output !== void 0 ? output : this.#accumulator
     });
     this.#currentChunkSpan = void 0;
+    this.#currentChunkType = void 0;
     this.#accumulator = {};
     this.#chunkSequence++;
   }
   /**
    * Create an event span (for single chunks like tool-call)
    */
-  #createEventSpan(chunkType, output) {
+  #createEventSpan(chunkType, output, options) {
     if (!this.#currentStepSpan) {
       this.startStep();
     }
@@ -5253,8 +7115,10 @@ var ModelSpanTracker = class {
       type: observability.SpanType.MODEL_CHUNK,
       attributes: {
         chunkType,
-        sequenceNumber: this.#chunkSequence
+        sequenceNumber: this.#chunkSequence,
+        ...options?.attributes
       },
+      metadata: options?.metadata,
       output
     });
     if (span) {
@@ -5282,6 +7146,9 @@ var ModelSpanTracker = class {
         this.#startChunkSpan("text");
         break;
       case "text-delta":
+        if (this.#currentChunkType !== "text") {
+          this.#startChunkSpan("text");
+        }
         this.#appendToAccumulator("text", chunk.payload.text);
         break;
       case "text-end": {
@@ -5299,6 +7166,9 @@ var ModelSpanTracker = class {
         this.#startChunkSpan("reasoning");
         break;
       case "reasoning-delta":
+        if (this.#currentChunkType !== "reasoning") {
+          this.#startChunkSpan("reasoning");
+        }
         this.#appendToAccumulator("text", chunk.payload.text);
         break;
       case "reasoning-end": {
@@ -5345,7 +7215,7 @@ var ModelSpanTracker = class {
   #handleObjectChunk(chunk) {
     switch (chunk.type) {
       case "object":
-        if (!this.#hasActiveChunkSpan()) {
+        if (this.#currentChunkType !== "object") {
           this.#startChunkSpan("object");
         }
         break;
@@ -5355,75 +7225,27 @@ var ModelSpanTracker = class {
     }
   }
   /**
-   * Handle tool-output chunks from sub-agents.
-   * Consolidates streaming text/reasoning deltas into a single span per tool call.
+   * Handle tool-call-approval chunks.
+   * Creates a span for approval requests so they can be seen in traces for debugging.
    */
-  #handleToolOutputChunk(chunk) {
-    if (chunk.type !== "tool-output") return;
+  #handleToolApprovalChunk(chunk) {
+    if (chunk.type !== "tool-call-approval") return;
     const payload = chunk.payload;
-    const { output, toolCallId, toolName } = payload;
-    let acc = this.#toolOutputAccumulators.get(toolCallId);
-    if (!acc) {
-      if (!this.#currentStepSpan) {
-        this.startStep();
-      }
-      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 (!this.#currentStepSpan) {
+      this.startStep();
     }
-    if (acc.reasoning) {
-      output.reasoning = acc.reasoning;
+    const span = this.#currentStepSpan?.createEventSpan({
+      name: `chunk: 'tool-call-approval'`,
+      type: observability.SpanType.MODEL_CHUNK,
+      attributes: {
+        chunkType: "tool-call-approval",
+        sequenceNumber: this.#chunkSequence
+      },
+      output: payload
+    });
+    if (span) {
+      this.#chunkSequence++;
     }
-    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.
@@ -5474,36 +7296,60 @@ var ModelSpanTracker = class {
             case "step-finish":
               this.#endStepSpan(chunk.payload);
               break;
+            // Infrastructure chunks - skip creating spans for these
+            // They are either redundant, metadata-only, or error/control flow
             case "raw":
-            // Skip raw chunks as they're redundant
+            // Redundant raw data
             case "start":
+            // Stream start marker
             case "finish":
+            // Stream finish marker (step-finish already captures this)
+            case "response-metadata":
+            // Response metadata (not semantic content)
+            case "source":
+            // Source references (metadata)
+            case "file":
+            // Binary file data (too large/not semantic)
+            case "error":
+            // Error handling
+            case "abort":
+            // Abort signal
+            case "tripwire":
+            // Processor rejection
+            case "watch":
+            // Internal watch event
+            case "tool-error":
+            // Tool error handling
+            case "tool-call-suspended":
+            // Suspension (not content)
+            case "reasoning-signature":
+            // Signature metadata
+            case "redacted-reasoning":
+            // Redacted content metadata
+            case "step-output":
+              break;
+            case "tool-call-approval":
+              this.#handleToolApprovalChunk(chunk);
               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;
-              if (outputPayload && typeof outputPayload === "object" && "data" in outputPayload) {
-                const typedPayload = outputPayload;
-                outputPayload = { ...typedPayload };
-                if (typedPayload.data) {
-                  outputPayload.size = typeof typedPayload.data === "string" ? typedPayload.data.length : typedPayload.data instanceof Uint8Array ? typedPayload.data.length : void 0;
-                  delete outputPayload.data;
-                }
-              }
-              this.#createEventSpan(chunk.type, outputPayload);
+              const {
+                // Metadata - tool call context (unique to tool-result chunks)
+                toolCallId,
+                toolName,
+                isError,
+                dynamic,
+                providerExecuted,
+                providerMetadata,
+                // Output - the actual result
+                result} = chunk.payload || {};
+              const metadata = { toolCallId, toolName };
+              if (isError !== void 0) metadata.isError = isError;
+              if (dynamic !== void 0) metadata.dynamic = dynamic;
+              if (providerExecuted !== void 0) metadata.providerExecuted = providerExecuted;
+              if (providerMetadata !== void 0) metadata.providerMetadata = providerMetadata;
+              this.#createEventSpan(chunk.type, result, { metadata });
               break;
             }
           }
@@ -5519,7 +7365,11 @@ var DEFAULT_KEYS_TO_STRIP = /* @__PURE__ */ new Set([
   "experimental_providerMetadata",
   "providerMetadata",
   "steps",
-  "tracingContext"
+  "tracingContext",
+  "execute",
+  // Tool execute functions
+  "validate"
+  // Schema validate functions
 ]);
 var DEFAULT_DEEP_CLEAN_OPTIONS = Object.freeze({
   keysToStrip: DEFAULT_KEYS_TO_STRIP,
@@ -5528,12 +7378,68 @@ var DEFAULT_DEEP_CLEAN_OPTIONS = Object.freeze({
   maxArrayLength: 50,
   maxObjectKeys: 50
 });
+function mergeSerializationOptions(userOptions) {
+  if (!userOptions) {
+    return DEFAULT_DEEP_CLEAN_OPTIONS;
+  }
+  return {
+    keysToStrip: DEFAULT_KEYS_TO_STRIP,
+    maxDepth: userOptions.maxDepth ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxDepth,
+    maxStringLength: userOptions.maxStringLength ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxStringLength,
+    maxArrayLength: userOptions.maxArrayLength ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxArrayLength,
+    maxObjectKeys: userOptions.maxObjectKeys ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxObjectKeys
+  };
+}
 function truncateString(s, maxChars) {
   if (s.length <= maxChars) {
     return s;
   }
   return s.slice(0, maxChars) + "\u2026[truncated]";
 }
+function isJsonSchema(val) {
+  if (typeof val !== "object" || val === null) return false;
+  if (val.$schema && typeof val.$schema === "string" && val.$schema.includes("json-schema")) {
+    return true;
+  }
+  if (val.type === "object" && val.properties && typeof val.properties === "object") {
+    return true;
+  }
+  return false;
+}
+function compressJsonSchema(schema, depth = 0) {
+  if (depth > 3) {
+    return schema.type || "object";
+  }
+  if (schema.type !== "object" || !schema.properties) {
+    return schema.type || schema;
+  }
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const compressed = {};
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    const prop = propSchema;
+    let value = prop.type || "unknown";
+    if (prop.type === "object" && prop.properties) {
+      value = compressJsonSchema(prop, depth + 1);
+      if (required.has(key)) {
+        compressed[key + " (required)"] = value;
+        continue;
+      }
+    } else if (prop.type === "array" && prop.items) {
+      if (prop.items.type === "object" && prop.items.properties) {
+        value = [compressJsonSchema(prop.items, depth + 1)];
+      } else {
+        value = `${prop.items.type || "any"}[]`;
+      }
+    } else if (prop.enum) {
+      value = prop.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    if (required.has(key) && typeof value === "string") {
+      value += " (required)";
+    }
+    compressed[key] = value;
+  }
+  return compressed;
+}
 function deepClean(value, options = DEFAULT_DEEP_CLEAN_OPTIONS) {
   const { keysToStrip, maxDepth, maxStringLength, maxArrayLength, maxObjectKeys } = options;
   const seen = /* @__PURE__ */ new WeakSet();
@@ -5593,6 +7499,15 @@ function deepClean(value, options = DEFAULT_DEEP_CLEAN_OPTIONS) {
     if (val instanceof ArrayBuffer) {
       return `[ArrayBuffer byteLength=${val.byteLength}]`;
     }
+    if (typeof val.serializeForSpan === "function") {
+      try {
+        return helper(val.serializeForSpan(), depth);
+      } catch {
+      }
+    }
+    if (isJsonSchema(val)) {
+      return helper(compressJsonSchema(val), depth);
+    }
     const cleaned = {};
     const entries = Object.entries(val);
     let keyCount = 0;
@@ -5684,25 +7599,30 @@ var BaseSpan = class {
   entityName;
   /** Parent span ID (for root spans that are children of external spans) */
   parentSpanId;
+  /** Deep clean options for serialization */
+  deepCleanOptions;
   constructor(options, observabilityInstance) {
+    const serializationOptions = observabilityInstance.getConfig().serializationOptions;
+    this.deepCleanOptions = mergeSerializationOptions(serializationOptions);
     this.name = options.name;
     this.type = options.type;
-    this.attributes = deepClean(options.attributes) || {};
-    this.metadata = deepClean(options.metadata);
+    this.attributes = deepClean(options.attributes, this.deepCleanOptions) || {};
+    this.metadata = deepClean(options.metadata, this.deepCleanOptions);
     this.parent = options.parent;
-    this.startTime = /* @__PURE__ */ new Date();
+    this.startTime = options.startTime ?? /* @__PURE__ */ new Date();
     this.observabilityInstance = observabilityInstance;
     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;
-    this.entityType = options.entityType;
-    this.entityId = options.entityId;
-    this.entityName = options.entityName;
+    const entityParent = this.getParentSpan(false);
+    this.entityType = options.entityType ?? entityParent?.entityType;
+    this.entityId = options.entityId ?? entityParent?.entityId;
+    this.entityName = options.entityName ?? entityParent?.entityName;
     if (this.isEvent) {
-      this.output = deepClean(options.output);
+      this.output = deepClean(options.output, this.deepCleanOptions);
     } else {
-      this.input = deepClean(options.input);
+      this.input = deepClean(options.input, this.deepCleanOptions);
     }
   }
   createChildSpan(options) {
@@ -5725,14 +7645,25 @@ var BaseSpan = class {
   get isRootSpan() {
     return !this.parent;
   }
+  /** Get the closest parent span, optionally skipping internal spans */
+  getParentSpan(includeInternalSpans) {
+    if (!this.parent) {
+      return void 0;
+    }
+    if (includeInternalSpans) return this.parent;
+    if (this.parent.isInternal) return this.parent.getParentSpan(includeInternalSpans);
+    return this.parent;
+  }
   /** Get the closest parent spanId that isn't an internal span */
   getParentSpanId(includeInternalSpans) {
     if (!this.parent) {
       return this.parentSpanId;
     }
-    if (includeInternalSpans) return this.parent.id;
-    if (this.parent.isInternal) return this.parent.getParentSpanId(includeInternalSpans);
-    return this.parent.id;
+    const parentSpan = this.getParentSpan(includeInternalSpans);
+    if (parentSpan) {
+      return parentSpan.id;
+    }
+    return this.parent.getParentSpanId(includeInternalSpans);
   }
   /** Find the closest parent span of a specific type by walking up the parent chain */
   findParent(spanType) {
@@ -5747,6 +7678,8 @@ var BaseSpan = class {
   }
   /** Returns a lightweight span ready for export */
   exportSpan(includeInternalSpans) {
+    const hideInput = this.traceState?.hideInput ?? false;
+    const hideOutput = this.traceState?.hideOutput ?? false;
     return {
       id: this.id,
       traceId: this.traceId,
@@ -5759,8 +7692,8 @@ var BaseSpan = class {
       metadata: this.metadata,
       startTime: this.startTime,
       endTime: this.endTime,
-      input: this.input,
-      output: this.output,
+      input: hideInput ? void 0 : this.input,
+      output: hideOutput ? void 0 : this.output,
       errorInfo: this.errorInfo,
       isEvent: this.isEvent,
       isRootSpan: this.isRootSpan,
@@ -5800,6 +7733,14 @@ var DefaultSpan = class extends BaseSpan {
   traceId;
   constructor(options, observabilityInstance) {
     super(options, observabilityInstance);
+    if (options.spanId && options.traceId) {
+      this.id = options.spanId;
+      this.traceId = options.traceId;
+      if (options.parentSpanId) {
+        this.parentSpanId = options.parentSpanId;
+      }
+      return;
+    }
     const bridge = observabilityInstance.getBridge();
     if (bridge && !this.isInternal) {
       const bridgeIds = bridge.createSpan(options);
@@ -5834,13 +7775,13 @@ var DefaultSpan = class extends BaseSpan {
     }
     this.endTime = /* @__PURE__ */ new Date();
     if (options?.output !== void 0) {
-      this.output = deepClean(options.output);
+      this.output = deepClean(options.output, this.deepCleanOptions);
     }
     if (options?.attributes) {
-      this.attributes = { ...this.attributes, ...deepClean(options.attributes) };
+      this.attributes = { ...this.attributes, ...deepClean(options.attributes, this.deepCleanOptions) };
     }
     if (options?.metadata) {
-      this.metadata = { ...this.metadata, ...deepClean(options.metadata) };
+      this.metadata = { ...this.metadata, ...deepClean(options.metadata, this.deepCleanOptions) };
     }
   }
   error(options) {
@@ -5858,10 +7799,10 @@ var DefaultSpan = class extends BaseSpan {
       message: error$1.message
     };
     if (attributes) {
-      this.attributes = { ...this.attributes, ...deepClean(attributes) };
+      this.attributes = { ...this.attributes, ...deepClean(attributes, this.deepCleanOptions) };
     }
     if (metadata) {
-      this.metadata = { ...this.metadata, ...deepClean(metadata) };
+      this.metadata = { ...this.metadata, ...deepClean(metadata, this.deepCleanOptions) };
     }
     if (endSpan) {
       this.end();
@@ -5874,16 +7815,16 @@ var DefaultSpan = class extends BaseSpan {
       return;
     }
     if (options.input !== void 0) {
-      this.input = deepClean(options.input);
+      this.input = deepClean(options.input, this.deepCleanOptions);
     }
     if (options.output !== void 0) {
-      this.output = deepClean(options.output);
+      this.output = deepClean(options.output, this.deepCleanOptions);
     }
     if (options.attributes) {
-      this.attributes = { ...this.attributes, ...deepClean(options.attributes) };
+      this.attributes = { ...this.attributes, ...deepClean(options.attributes, this.deepCleanOptions) };
     }
     if (options.metadata) {
-      this.metadata = { ...this.metadata, ...deepClean(options.metadata) };
+      this.metadata = { ...this.metadata, ...deepClean(options.metadata, this.deepCleanOptions) };
     }
   }
   get isValid() {
@@ -5974,7 +7915,8 @@ var BaseObservabilityInstance = class extends base.MastraBase {
       spanOutputProcessors: config.spanOutputProcessors ?? [],
       bridge: config.bridge ?? void 0,
       includeInternalSpans: config.includeInternalSpans ?? false,
-      requestContextKeys: config.requestContextKeys ?? []
+      requestContextKeys: config.requestContextKeys ?? [],
+      serializationOptions: config.serializationOptions
     };
     if (this.config.bridge?.init) {
       this.config.bridge.init({ config: this.config });
@@ -6012,11 +7954,26 @@ var BaseObservabilityInstance = class extends base.MastraBase {
   // ============================================================================
   /**
    * Start a new span of a specific SpanType
+   *
+   * Sampling Decision:
+   * - For root spans (no parent): Perform sampling check using the configured strategy
+   * - For child spans: Inherit the sampling decision from the parent
+   *   - If parent is a NoOpSpan (not sampled), child is also a NoOpSpan
+   *   - If parent is a valid span (sampled), child is also sampled
+   *
+   * This ensures trace-level sampling: either all spans in a trace are sampled or none are.
+   * See: https://github.com/mastra-ai/mastra/issues/11504
    */
   startSpan(options) {
     const { customSamplerOptions, requestContext, metadata, tracingOptions, ...rest } = options;
-    if (!this.shouldSample(customSamplerOptions)) {
-      return new NoOpSpan({ ...rest, metadata }, this);
+    if (options.parent) {
+      if (!options.parent.isValid) {
+        return new NoOpSpan({ ...rest, metadata }, this);
+      }
+    } else {
+      if (!this.shouldSample(customSamplerOptions)) {
+        return new NoOpSpan({ ...rest, metadata }, this);
+      }
     }
     let traceState;
     if (options.parent) {
@@ -6028,8 +7985,12 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     const mergedMetadata = metadata || tracingMetadata ? { ...metadata, ...tracingMetadata } : void 0;
     const enrichedMetadata = this.extractMetadataFromRequestContext(requestContext, mergedMetadata, traceState);
     const tags = !options.parent ? tracingOptions?.tags : void 0;
+    const traceId = !options.parent ? options.traceId ?? tracingOptions?.traceId : options.traceId;
+    const parentSpanId = !options.parent ? options.parentSpanId ?? tracingOptions?.parentSpanId : options.parentSpanId;
     const span = this.createSpan({
       ...rest,
+      traceId,
+      parentSpanId,
       metadata: enrichedMetadata,
       traceState,
       tags
@@ -6042,6 +8003,37 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     }
     return span;
   }
+  /**
+   * Rebuild a span from exported data for lifecycle operations.
+   * Used by durable execution engines (e.g., Inngest) to end/update spans
+   * that were created in a previous durable operation.
+   *
+   * The rebuilt span:
+   * - Does NOT emit SPAN_STARTED (assumes original span already did)
+   * - Can have end(), update(), error() called on it
+   * - Will emit SPAN_ENDED or SPAN_UPDATED when those methods are called
+   *
+   * @param cached - The exported span data to rebuild from
+   * @returns A span that can have lifecycle methods called on it
+   */
+  rebuildSpan(cached) {
+    const span = this.createSpan({
+      name: cached.name,
+      type: cached.type,
+      traceId: cached.traceId,
+      spanId: cached.id,
+      parentSpanId: cached.parentSpanId,
+      startTime: cached.startTime instanceof Date ? cached.startTime : new Date(cached.startTime),
+      input: cached.input,
+      attributes: cached.attributes,
+      metadata: cached.metadata,
+      entityType: cached.entityType,
+      entityId: cached.entityId,
+      entityName: cached.entityName
+    });
+    this.wireSpanLifecycle(span);
+    return span;
+  }
   // ============================================================================
   // Configuration Management
   // ============================================================================
@@ -6144,11 +8136,15 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     const configuredKeys = this.config.requestContextKeys ?? [];
     const additionalKeys = tracingOptions?.requestContextKeys ?? [];
     const allKeys = [...configuredKeys, ...additionalKeys];
-    if (allKeys.length === 0) {
+    const hideInput = tracingOptions?.hideInput;
+    const hideOutput = tracingOptions?.hideOutput;
+    if (allKeys.length === 0 && !hideInput && !hideOutput) {
       return void 0;
     }
     return {
-      requestContextKeys: allKeys
+      requestContextKeys: allKeys,
+      ...hideInput !== void 0 && { hideInput },
+      ...hideOutput !== void 0 && { hideOutput }
     };
   }
   /**
@@ -6279,6 +8275,29 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     this.logger.debug(`[Observability] Initialization started [name=${this.name}]`);
     this.logger.info(`[Observability] Initialized successfully [name=${this.name}]`);
   }
+  /**
+   * Force flush any buffered/queued spans from all exporters and the bridge
+   * without shutting down the observability instance.
+   *
+   * This is useful in serverless environments (like Vercel's fluid compute) where
+   * you need to ensure all spans are exported before the runtime instance is
+   * terminated, while keeping the observability system active for future requests.
+   */
+  async flush() {
+    this.logger.debug(`[Observability] Flush started [name=${this.name}]`);
+    const flushPromises = [...this.exporters.map((e) => e.flush())];
+    if (this.config.bridge) {
+      flushPromises.push(this.config.bridge.flush());
+    }
+    const results = await Promise.allSettled(flushPromises);
+    results.forEach((result, index) => {
+      if (result.status === "rejected") {
+        const targetName = index < this.exporters.length ? this.exporters[index]?.name : "bridge";
+        this.logger.error(`[Observability] Flush error [target=${targetName}]`, result.reason);
+      }
+    });
+    this.logger.debug(`[Observability] Flush completed [name=${this.name}]`);
+  }
   /**
    * Shutdown Observability and clean up resources
    */
@@ -6588,6 +8607,9 @@ var Observability = class extends base.MastraBase {
       }
     }
     if (config.default?.enabled) {
+      console.warn(
+        '[Mastra Observability] The "default: { enabled: true }" configuration is deprecated and will be removed in a future version. Please use explicit configs with DefaultExporter, CloudExporter, and SensitiveDataFilter instead. See https://mastra.ai/docs/observability/tracing/overview for the recommended configuration.'
+      );
       const defaultInstance = new DefaultObservabilityInstance({
         serviceName: "mastra",
         name: "default",
@@ -6685,19 +8707,25 @@ exports.DEFAULT_KEYS_TO_STRIP = DEFAULT_KEYS_TO_STRIP;
 exports.DefaultExporter = DefaultExporter;
 exports.DefaultObservabilityInstance = DefaultObservabilityInstance;
 exports.DefaultSpan = DefaultSpan;
+exports.JsonExporter = JsonExporter;
 exports.ModelSpanTracker = ModelSpanTracker;
 exports.NoOpSpan = NoOpSpan;
 exports.Observability = Observability;
 exports.SamplingStrategyType = SamplingStrategyType;
 exports.SensitiveDataFilter = SensitiveDataFilter;
 exports.TestExporter = TestExporter;
+exports.TraceData = TraceData;
+exports.TrackingExporter = TrackingExporter;
 exports.buildTracingOptions = buildTracingOptions;
+exports.chainFormatters = chainFormatters;
 exports.deepClean = deepClean;
 exports.getExternalParentId = getExternalParentId;
+exports.mergeSerializationOptions = mergeSerializationOptions;
 exports.observabilityConfigValueSchema = observabilityConfigValueSchema;
 exports.observabilityInstanceConfigSchema = observabilityInstanceConfigSchema;
 exports.observabilityRegistryConfigSchema = observabilityRegistryConfigSchema;
 exports.samplingStrategySchema = samplingStrategySchema;
+exports.serializationOptionsSchema = serializationOptionsSchema;
 exports.truncateString = truncateString;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map