@mastra/observability 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/index.cjs

@@ -4163,6 +4163,8 @@ var observabilityRegistryConfigSchema = external_exports.object({
 var BaseExporter = class {
   /** Mastra logger instance */
   logger;
+  /** Base configuration (accessible by subclasses) */
+  baseConfig;
   /** Whether this exporter is disabled */
   #disabled = false;
   /** Public getter for disabled state */
@@ -4173,6 +4175,7 @@ var BaseExporter = class {
    * 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 });
   }
@@ -4210,17 +4213,59 @@ var BaseExporter = class {
     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
@@ -4892,6 +4937,10 @@ var TrackingExporter = class extends BaseExporter {
   /**
    * 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
    */
@@ -5105,8 +5154,31 @@ var TrackingExporter = class extends BaseExporter {
     return this.#traceMap.size;
   }
   // ============================================================================
-  // Shutdown Hooks (Override in subclass as needed)
+  // 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.
@@ -5164,9 +5236,20 @@ var TrackingExporter = class extends BaseExporter {
     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";
-  config;
+  cloudConfig;
   buffer;
   flushTimer = null;
   constructor(config = {}) {
@@ -5176,7 +5259,7 @@ var CloudExporter = class extends BaseExporter {
       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.config = {
+    this.cloudConfig = {
       logger: this.logger,
       logLevel: config.logLevel ?? logger.LogLevel.INFO,
       maxBatchSize: config.maxBatchSize ?? 1e3,
@@ -5234,12 +5317,12 @@ var CloudExporter = class extends BaseExporter {
     return spanRecord;
   }
   shouldFlush() {
-    if (this.buffer.totalSize >= this.config.maxBatchSize) {
+    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.config.maxBatchWaitMs) {
+      if (elapsed >= this.cloudConfig.maxBatchWaitMs) {
         return true;
       }
     }
@@ -5262,9 +5345,9 @@ var CloudExporter = class extends BaseExporter {
         this.logger.trackException(mastraError);
         this.logger.error("Scheduled flush failed", mastraError);
       });
-    }, this.config.maxBatchWaitMs);
+    }, this.cloudConfig.maxBatchWaitMs);
   }
-  async flush() {
+  async flushBuffer() {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
@@ -5274,7 +5357,7 @@ var CloudExporter = class extends BaseExporter {
     }
     const startTime = Date.now();
     const spansCopy = [...this.buffer.spans];
-    const flushReason = this.buffer.totalSize >= this.config.maxBatchSize ? "size" : "time";
+    const flushReason = this.buffer.totalSize >= this.cloudConfig.maxBatchSize ? "size" : "time";
     this.resetBuffer();
     try {
       await this.batchUpload(spansCopy);
@@ -5305,7 +5388,7 @@ var CloudExporter = class extends BaseExporter {
    */
   async batchUpload(spans) {
     const headers = {
-      Authorization: `Bearer ${this.config.accessToken}`,
+      Authorization: `Bearer ${this.cloudConfig.accessToken}`,
       "Content-Type": "application/json"
     };
     const options = {
@@ -5313,13 +5396,29 @@ var CloudExporter = class extends BaseExporter {
       headers,
       body: JSON.stringify({ spans })
     };
-    await utils.fetchWithRetry(this.config.endpoint, options, this.config.maxRetries);
+    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;
@@ -5328,27 +5427,22 @@ var CloudExporter = class extends BaseExporter {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
     }
-    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);
-      }
+    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");
   }
@@ -5652,7 +5746,7 @@ var DefaultExporter = class extends BaseExporter {
       clearTimeout(this.#flushTimer);
     }
     this.#flushTimer = setTimeout(() => {
-      this.flush().catch((error) => {
+      this.flushBuffer().catch((error) => {
         this.logger.error("Scheduled flush failed", {
           error: error instanceof Error ? error.message : String(error)
         });
@@ -5786,7 +5880,7 @@ var DefaultExporter = class extends BaseExporter {
   handleBatchWithUpdatesEvent(event) {
     this.addToBuffer(event);
     if (this.shouldFlush()) {
-      this.flush().catch((error) => {
+      this.flushBuffer().catch((error) => {
         this.logger.error("Batch flush failed", {
           error: error instanceof Error ? error.message : String(error)
         });
@@ -5802,7 +5896,7 @@ var DefaultExporter = class extends BaseExporter {
     if (event.type === observability.TracingEventType.SPAN_ENDED) {
       this.addToBuffer(event);
       if (this.shouldFlush()) {
-        this.flush().catch((error) => {
+        this.flushBuffer().catch((error) => {
           this.logger.error("Batch flush failed", {
             error: error instanceof Error ? error.message : String(error)
           });
@@ -5819,9 +5913,9 @@ var DefaultExporter = class extends BaseExporter {
     return this.#config.retryDelayMs * Math.pow(2, attempt);
   }
   /**
-   * Flushes the current buffer to storage with retry logic
+   * Flushes the current buffer to storage with retry logic (internal implementation)
    */
-  async flush() {
+  async flushBuffer() {
     if (!this.#observability) {
       this.logger.debug("Cannot flush traces. Observability storage is not initialized");
       return;
@@ -5928,23 +6022,25 @@ var DefaultExporter = class extends BaseExporter {
         break;
     }
   }
+  /**
+   * 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() {
     if (this.#flushTimer) {
       clearTimeout(this.#flushTimer);
       this.#flushTimer = null;
     }
-    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)
-        });
-      }
-    }
+    await this.flush();
     this.logger.info("DefaultExporter shutdown complete");
   }
 };
@@ -7318,6 +7414,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
    */
@@ -7736,6 +7855,7 @@ exports.TestExporter = TestExporter;
 exports.TraceData = TraceData;
 exports.TrackingExporter = TrackingExporter;
 exports.buildTracingOptions = buildTracingOptions;
+exports.chainFormatters = chainFormatters;
 exports.deepClean = deepClean;
 exports.getExternalParentId = getExternalParentId;
 exports.mergeSerializationOptions = mergeSerializationOptions;