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

package/dist/index.js

@@ -4253,6 +4253,18 @@ var BaseExporter = class {
     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
    *
@@ -5140,8 +5152,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.
@@ -5310,7 +5345,7 @@ var CloudExporter = class extends BaseExporter {
       });
     }, this.cloudConfig.maxBatchWaitMs);
   }
-  async flush() {
+  async flushBuffer() {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
@@ -5366,6 +5401,22 @@ var CloudExporter = class extends BaseExporter {
     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;
@@ -5374,27 +5425,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) {
-        const mastraError = new MastraError(
-          {
-            id: `CLOUD_EXPORTER_FAILED_TO_FLUSH_REMAINING_EVENTS_DURING_SHUTDOWN`,
-            domain: ErrorDomain.MASTRA_OBSERVABILITY,
-            category: ErrorCategory.USER,
-            details: {
-              remainingEvents: this.buffer.totalSize
-            }
-          },
-          error
-        );
-        this.logger.trackException(mastraError);
-        this.logger.error("Failed to flush remaining events during shutdown", mastraError);
-      }
+    try {
+      await this.flush();
+    } catch (error) {
+      const mastraError = new MastraError(
+        {
+          id: `CLOUD_EXPORTER_FAILED_TO_FLUSH_REMAINING_EVENTS_DURING_SHUTDOWN`,
+          domain: ErrorDomain.MASTRA_OBSERVABILITY,
+          category: ErrorCategory.USER,
+          details: {
+            remainingEvents: this.buffer.totalSize
+          }
+        },
+        error
+      );
+      this.logger.trackException(mastraError);
+      this.logger.error("Failed to flush remaining events during shutdown", mastraError);
     }
     this.logger.info("CloudExporter shutdown complete");
   }
@@ -5698,7 +5744,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)
         });
@@ -5832,7 +5878,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)
         });
@@ -5848,7 +5894,7 @@ var DefaultExporter = class extends BaseExporter {
     if (event.type === 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)
           });
@@ -5865,9 +5911,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;
@@ -5974,23 +6020,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");
   }
 };
@@ -7364,6 +7412,29 @@ var BaseObservabilityInstance = class extends 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
    */