@mastra/observability 1.2.1 → 1.3.0

package/dist/index.cjs

@@ -5,9 +5,6 @@ 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;
@@ -4245,6 +4242,19 @@ var BaseExporter = class {
     }
     return event;
   }
+  /**
+   * Default onTracingEvent handler that delegates to exportTracingEvent.
+   *
+   * This provides backward compatibility: existing exporters that only implement
+   * _exportTracingEvent will automatically receive tracing events routed through
+   * the ObservabilityBus. Subclasses can override this if they need different
+   * routing behavior for bus-delivered events.
+   *
+   * Handler presence on ObservabilityExporter = signal support.
+   */
+  onTracingEvent(event) {
+    return this.exportTracingEvent(event);
+  }
   /**
    * Export a tracing event
    *
@@ -6073,59 +6083,58 @@ var DefaultExporter = class extends BaseExporter {
     this.logger.info("DefaultExporter shutdown complete");
   }
 };
-
-// src/exporters/test.ts
-var TestExporter = class extends BaseExporter {
-  name = "tracing-test-exporter";
-  #events = [];
-  constructor(config = {}) {
-    super(config);
-  }
-  async _exportTracingEvent(event) {
-    this.#events.push(event);
-  }
-  clearEvents() {
-    this.#events = [];
-  }
-  get events() {
-    return this.#events;
-  }
-  async shutdown() {
-    this.logger.info("TestExporter shutdown");
-  }
-};
 var _snapshotsDir;
-function getSnapshotsDir() {
+async function getSnapshotsDir() {
   if (!_snapshotsDir) {
     if (typeof (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) !== "string") {
       throw new Error(
         "Snapshot functionality requires a Node.js environment. import.meta.url is not available in this runtime."
       );
     }
-    const __filename = 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)));
-    const __dirname = path.dirname(__filename);
-    _snapshotsDir = path.join(__dirname, "..", "__snapshots__");
+    const { fileURLToPath } = await import('url');
+    const { dirname, join } = await import('path');
+    const __filename = fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+    const __dirname = dirname(__filename);
+    _snapshotsDir = join(__dirname, "..", "__snapshots__");
   }
   return _snapshotsDir;
 }
-var JsonExporter = class extends BaseExporter {
-  name = "json-exporter";
-  /** All collected events */
-  #events = [];
+var TestExporter = class extends BaseExporter {
+  name = "test-exporter";
+  /** All collected tracing events */
+  #tracingEvents = [];
   /** Per-span state tracking */
   #spanStates = /* @__PURE__ */ new Map();
-  /** Logs for debugging */
-  #logs = [];
+  /** All collected log events */
+  #logEvents = [];
+  /** All collected metric events */
+  #metricEvents = [];
+  /** All collected score events */
+  #scoreEvents = [];
+  /** All collected feedback events */
+  #feedbackEvents = [];
+  /** Debug logs for the exporter itself */
+  #debugLogs = [];
   /** Configuration */
   #config;
+  /** Internal metrics tracking */
+  #internalMetrics;
   constructor(config = {}) {
     super(config);
     this.#config = {
       validateLifecycle: true,
       storeLogs: true,
       jsonIndent: 2,
+      logMetricsOnFlush: true,
       ...config
     };
+    this.#internalMetrics = {
+      startedAt: /* @__PURE__ */ new Date(),
+      lastEventAt: null,
+      totalEventsReceived: 0,
+      bySignal: { tracing: 0, log: 0, metric: 0, score: 0, feedback: 0 },
+      flushCount: 0
+    };
   }
   /**
    * Process incoming tracing events with lifecycle tracking
@@ -6133,9 +6142,10 @@ var JsonExporter = class extends BaseExporter {
   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)})`;
+    this.#trackEvent("tracing");
+    const logMessage = `[TestExporter] ${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);
+      this.#debugLogs.push(logMessage);
     }
     const state = this.#spanStates.get(spanId) || {
       hasStart: false,
@@ -6158,7 +6168,67 @@ var JsonExporter = class extends BaseExporter {
     }
     state.events.push(event);
     this.#spanStates.set(spanId, state);
-    this.#events.push(event);
+    this.#tracingEvents.push(event);
+  }
+  // ============================================================================
+  // Signal Handlers (Logs, Metrics, Scores, Feedback)
+  // ============================================================================
+  /**
+   * Process incoming log events
+   */
+  async onLogEvent(event) {
+    this.#trackEvent("log");
+    if (this.#config.storeLogs) {
+      const log = event.log;
+      const logMessage = `[TestExporter] log.${log.level}: "${log.message}"${log.traceId ? ` (trace: ${log.traceId.slice(-8)})` : ""}`;
+      this.#debugLogs.push(logMessage);
+    }
+    this.#logEvents.push(event);
+  }
+  /**
+   * Process incoming metric events
+   */
+  async onMetricEvent(event) {
+    this.#trackEvent("metric");
+    if (this.#config.storeLogs) {
+      const metric = event.metric;
+      const labelsStr = Object.entries(metric.labels).map(([k, v]) => `${k}=${v}`).join(", ");
+      const logMessage = `[TestExporter] metric.${metric.metricType}: ${metric.name}=${metric.value}${labelsStr ? ` {${labelsStr}}` : ""}`;
+      this.#debugLogs.push(logMessage);
+    }
+    this.#metricEvents.push(event);
+  }
+  /**
+   * Process incoming score events
+   */
+  async onScoreEvent(event) {
+    this.#trackEvent("score");
+    if (this.#config.storeLogs) {
+      const score = event.score;
+      const logMessage = `[TestExporter] score: ${score.scorerName}=${score.score} (trace: ${score.traceId.slice(-8)}${score.spanId ? `, span: ${score.spanId.slice(-8)}` : ""})`;
+      this.#debugLogs.push(logMessage);
+    }
+    this.#scoreEvents.push(event);
+  }
+  /**
+   * Process incoming feedback events
+   */
+  async onFeedbackEvent(event) {
+    this.#trackEvent("feedback");
+    if (this.#config.storeLogs) {
+      const fb = event.feedback;
+      const logMessage = `[TestExporter] feedback: ${fb.feedbackType} from ${fb.source}=${fb.value} (trace: ${fb.traceId.slice(-8)}${fb.spanId ? `, span: ${fb.spanId.slice(-8)}` : ""})`;
+      this.#debugLogs.push(logMessage);
+    }
+    this.#feedbackEvents.push(event);
+  }
+  /**
+   * Track an event for internal metrics
+   */
+  #trackEvent(signal) {
+    this.#internalMetrics.lastEventAt = /* @__PURE__ */ new Date();
+    this.#internalMetrics.totalEventsReceived++;
+    this.#internalMetrics.bySignal[signal]++;
   }
   /**
    * Validate span lifecycle rules
@@ -6185,13 +6255,13 @@ var JsonExporter = class extends BaseExporter {
     }
   }
   // ============================================================================
-  // Query Methods
+  // Tracing Query Methods
   // ============================================================================
   /**
-   * Get all collected events
+   * Get all collected tracing events
    */
   get events() {
-    return [...this.#events];
+    return [...this.#tracingEvents];
   }
   /**
    * Get completed spans by SpanType (e.g., 'agent_run', 'tool_call')
@@ -6216,18 +6286,21 @@ var JsonExporter = class extends BaseExporter {
    * @returns Array of events of the specified type
    */
   getByEventType(type) {
-    return this.#events.filter((e) => e.type === type);
+    return this.#tracingEvents.filter((e) => e.type === type);
   }
   /**
    * 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
+   * @returns Object containing tracing events, final spans, plus logs/scores/feedback for the trace
    */
   getByTraceId(traceId) {
-    const events = this.#events.filter((e) => e.exportedSpan.traceId === traceId);
+    const events = this.#tracingEvents.filter((e) => e.exportedSpan.traceId === traceId);
     const spans = this.#getUniqueSpansFromEvents(events);
-    return { events, spans };
+    const logs = this.#logEvents.filter((e) => e.log.traceId === traceId).map((e) => e.log);
+    const scores = this.#scoreEvents.filter((e) => e.score.traceId === traceId).map((e) => e.score);
+    const feedback = this.#feedbackEvents.filter((e) => e.feedback.traceId === traceId).map((e) => e.feedback);
+    return { events, spans, logs, scores, feedback };
   }
   /**
    * Get all events for a specific span
@@ -6283,20 +6356,137 @@ var JsonExporter = class extends BaseExporter {
     }));
   }
   /**
-   * Get unique trace IDs from all collected spans
+   * Get unique trace IDs from all collected signals
    */
   getTraceIds() {
     const traceIds = /* @__PURE__ */ new Set();
-    for (const event of this.#events) {
+    for (const event of this.#tracingEvents) {
       traceIds.add(event.exportedSpan.traceId);
     }
+    for (const event of this.#logEvents) {
+      if (event.log.traceId) traceIds.add(event.log.traceId);
+    }
+    for (const event of this.#scoreEvents) {
+      traceIds.add(event.score.traceId);
+    }
+    for (const event of this.#feedbackEvents) {
+      traceIds.add(event.feedback.traceId);
+    }
     return Array.from(traceIds);
   }
   // ============================================================================
+  // Log Query Methods
+  // ============================================================================
+  /**
+   * Get all collected log events
+   */
+  getLogEvents() {
+    return [...this.#logEvents];
+  }
+  /**
+   * Get all collected logs (unwrapped from events)
+   */
+  getAllLogs() {
+    return this.#logEvents.map((e) => e.log);
+  }
+  /**
+   * Get logs filtered by level
+   */
+  getLogsByLevel(level) {
+    return this.#logEvents.filter((e) => e.log.level === level).map((e) => e.log);
+  }
+  /**
+   * Get logs for a specific trace
+   */
+  getLogsByTraceId(traceId) {
+    return this.#logEvents.filter((e) => e.log.traceId === traceId).map((e) => e.log);
+  }
+  // ============================================================================
+  // Metric Query Methods
+  // ============================================================================
+  /**
+   * Get all collected metric events
+   */
+  getMetricEvents() {
+    return [...this.#metricEvents];
+  }
+  /**
+   * Get all collected metrics (unwrapped from events)
+   */
+  getAllMetrics() {
+    return this.#metricEvents.map((e) => e.metric);
+  }
+  /**
+   * Get metrics filtered by name
+   */
+  getMetricsByName(name) {
+    return this.#metricEvents.filter((e) => e.metric.name === name).map((e) => e.metric);
+  }
+  /**
+   * Get metrics filtered by type
+   */
+  getMetricsByType(metricType) {
+    return this.#metricEvents.filter((e) => e.metric.metricType === metricType).map((e) => e.metric);
+  }
+  // ============================================================================
+  // Score Query Methods
+  // ============================================================================
+  /**
+   * Get all collected score events
+   */
+  getScoreEvents() {
+    return [...this.#scoreEvents];
+  }
+  /**
+   * Get all collected scores (unwrapped from events)
+   */
+  getAllScores() {
+    return this.#scoreEvents.map((e) => e.score);
+  }
+  /**
+   * Get scores filtered by scorer name
+   */
+  getScoresByScorer(scorerName) {
+    return this.#scoreEvents.filter((e) => e.score.scorerName === scorerName).map((e) => e.score);
+  }
+  /**
+   * Get scores for a specific trace
+   */
+  getScoresByTraceId(traceId) {
+    return this.#scoreEvents.filter((e) => e.score.traceId === traceId).map((e) => e.score);
+  }
+  // ============================================================================
+  // Feedback Query Methods
+  // ============================================================================
+  /**
+   * Get all collected feedback events
+   */
+  getFeedbackEvents() {
+    return [...this.#feedbackEvents];
+  }
+  /**
+   * Get all collected feedback (unwrapped from events)
+   */
+  getAllFeedback() {
+    return this.#feedbackEvents.map((e) => e.feedback);
+  }
+  /**
+   * Get feedback filtered by type
+   */
+  getFeedbackByType(feedbackType) {
+    return this.#feedbackEvents.filter((e) => e.feedback.feedbackType === feedbackType).map((e) => e.feedback);
+  }
+  /**
+   * Get feedback for a specific trace
+   */
+  getFeedbackByTraceId(traceId) {
+    return this.#feedbackEvents.filter((e) => e.feedback.traceId === traceId).map((e) => e.feedback);
+  }
+  // ============================================================================
   // Statistics
   // ============================================================================
   /**
-   * Get comprehensive statistics about collected spans
+   * Get comprehensive statistics about all collected signals
    */
   getStatistics() {
     const bySpanType = {};
@@ -6314,18 +6504,52 @@ var JsonExporter = class extends BaseExporter {
         incompleteSpans++;
       }
     }
+    const logsByLevel = {};
+    for (const event of this.#logEvents) {
+      const level = event.log.level;
+      logsByLevel[level] = (logsByLevel[level] || 0) + 1;
+    }
+    const metricsByType = {};
+    const metricsByName = {};
+    for (const event of this.#metricEvents) {
+      const mType = event.metric.metricType;
+      metricsByType[mType] = (metricsByType[mType] || 0) + 1;
+      const mName = event.metric.name;
+      metricsByName[mName] = (metricsByName[mName] || 0) + 1;
+    }
+    const scoresByScorer = {};
+    for (const event of this.#scoreEvents) {
+      const scorer = event.score.scorerName;
+      scoresByScorer[scorer] = (scoresByScorer[scorer] || 0) + 1;
+    }
+    const feedbackByType = {};
+    for (const event of this.#feedbackEvents) {
+      const fbType = event.feedback.feedbackType;
+      feedbackByType[fbType] = (feedbackByType[fbType] || 0) + 1;
+    }
     return {
-      totalEvents: this.#events.length,
+      totalTracingEvents: this.#tracingEvents.length,
+      totalEvents: this.#tracingEvents.length,
+      // deprecated alias
       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
+        started: this.#tracingEvents.filter((e) => e.type === observability.TracingEventType.SPAN_STARTED).length,
+        updated: this.#tracingEvents.filter((e) => e.type === observability.TracingEventType.SPAN_UPDATED).length,
+        ended: this.#tracingEvents.filter((e) => e.type === observability.TracingEventType.SPAN_ENDED).length
       },
-      bySpanType
+      bySpanType,
+      totalLogs: this.#logEvents.length,
+      logsByLevel,
+      totalMetrics: this.#metricEvents.length,
+      metricsByType,
+      metricsByName,
+      totalScores: this.#scoreEvents.length,
+      scoresByScorer,
+      totalFeedback: this.#feedbackEvents.length,
+      feedbackByType
     };
   }
   // ============================================================================
@@ -6344,8 +6568,20 @@ var JsonExporter = class extends BaseExporter {
     const data = {
       spans: this.getAllSpans()
     };
+    if (this.#logEvents.length > 0) {
+      data.logs = this.getAllLogs();
+    }
+    if (this.#metricEvents.length > 0) {
+      data.metrics = this.getAllMetrics();
+    }
+    if (this.#scoreEvents.length > 0) {
+      data.scores = this.getAllScores();
+    }
+    if (this.#feedbackEvents.length > 0) {
+      data.feedback = this.getAllFeedback();
+    }
     if (includeEvents) {
-      data.events = this.#events;
+      data.events = this.#tracingEvents;
     }
     if (includeStats) {
       data.statistics = this.getStatistics();
@@ -6419,6 +6655,7 @@ var JsonExporter = class extends BaseExporter {
     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 embeddedPrefixedUuidTest = /([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)) {
@@ -6453,8 +6690,7 @@ var JsonExporter = class extends BaseExporter {
           const uuid = prefixMatch[2];
           return `${prefix}_${normalizeUuid(uuid, prefix)}`;
         }
-        if (embeddedPrefixedUuidRegex.test(value)) {
-          embeddedPrefixedUuidRegex.lastIndex = 0;
+        if (embeddedPrefixedUuidTest.test(value)) {
           return value.replace(embeddedPrefixedUuidRegex, (_match, prefix, uuid) => {
             return `${prefix}_${normalizeUuid(uuid, prefix)}`;
           });
@@ -6516,7 +6752,7 @@ var JsonExporter = class extends BaseExporter {
         normalizedSpan.output = normalizeValue(span.output);
       }
       if (span.errorInfo) {
-        normalizedSpan.errorInfo = span.errorInfo;
+        normalizedSpan.errorInfo = normalizeValue(span.errorInfo);
       }
       if (span.tags && span.tags.length > 0) {
         normalizedSpan.tags = span.tags;
@@ -6603,8 +6839,9 @@ var JsonExporter = class extends BaseExporter {
     } else {
       json = this.toJSON(options);
     }
-    await promises.writeFile(filePath, json, "utf-8");
-    this.logger.info(`JsonExporter: wrote ${this.#events.length} events to ${filePath}`);
+    const { writeFile } = await import('fs/promises');
+    await writeFile(filePath, json, "utf-8");
+    this.logger.info(`TestExporter: wrote ${this.#tracingEvents.length} tracing events to ${filePath}`);
   }
   /**
    * Assert that the current normalized tree matches a snapshot file.
@@ -6632,7 +6869,8 @@ var JsonExporter = class extends BaseExporter {
    * @throws Error if the snapshot doesn't match (and updateSnapshot is false)
    */
   async assertMatchesSnapshot(snapshotName, options) {
-    const snapshotPath = path.join(getSnapshotsDir(), snapshotName);
+    const { join } = await import('path');
+    const snapshotPath = join(await getSnapshotsDir(), snapshotName);
     const normalizedTree = this.buildNormalizedTree();
     const structureGraph = this.generateStructureGraph(normalizedTree);
     const currentData = {
@@ -6642,17 +6880,29 @@ var JsonExporter = class extends BaseExporter {
     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}`);
+      const { writeFile } = await import('fs/promises');
+      await writeFile(snapshotPath, currentJson, "utf-8");
+      this.logger.info(`TestExporter: updated snapshot ${snapshotPath}`);
       return;
     }
     let snapshotData;
+    let snapshotContent;
+    try {
+      const { readFile } = await import('fs/promises');
+      snapshotContent = await readFile(snapshotPath, "utf-8");
+    } catch (err) {
+      if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+        throw new Error(
+          `Snapshot file not found: ${snapshotPath}
+Run with { updateSnapshot: true } to create it.`
+        );
+      }
+      throw err;
+    }
     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.`);
+    } catch (err) {
+      throw new Error(`Failed to parse snapshot ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}`);
     }
     let expectedSpans;
     let expectedStructure;
@@ -6853,17 +7103,19 @@ Run with { updateSnapshot: true } to update.`
   // Debugging Helpers
   // ============================================================================
   /**
-   * Get all stored logs
+   * Get all stored debug logs (internal exporter logging, not signal logs)
    */
   getLogs() {
-    return [...this.#logs];
+    return [...this.#debugLogs];
   }
   /**
-   * Dump logs to console for debugging (uses console.error for visibility in test output)
+   * Dump debug 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("\n=== TestExporter Logs ===");
+    this.#debugLogs.forEach((log) => {
+      console.error(log);
+    });
     console.error("=== End Logs ===\n");
   }
   /**
@@ -6888,12 +7140,16 @@ Run with { updateSnapshot: true } to update.`
   // Reset & Lifecycle
   // ============================================================================
   /**
-   * Clear all collected events and state
+   * Clear all collected events and state across all signals
    */
   clearEvents() {
-    this.#events = [];
+    this.#tracingEvents = [];
     this.#spanStates.clear();
-    this.#logs = [];
+    this.#logEvents = [];
+    this.#metricEvents = [];
+    this.#scoreEvents = [];
+    this.#feedbackEvents = [];
+    this.#debugLogs = [];
   }
   /**
    * Alias for clearEvents (compatibility with TestExporter)
@@ -6901,8 +7157,42 @@ Run with { updateSnapshot: true } to update.`
   reset() {
     this.clearEvents();
   }
+  /**
+   * Get internal metrics about the exporter's own activity.
+   */
+  getInternalMetrics() {
+    const json = this.toJSON({ includeEvents: false, includeStats: false });
+    return {
+      startedAt: this.#internalMetrics.startedAt,
+      lastEventAt: this.#internalMetrics.lastEventAt,
+      totalEventsReceived: this.#internalMetrics.totalEventsReceived,
+      bySignal: { ...this.#internalMetrics.bySignal },
+      flushCount: this.#internalMetrics.flushCount,
+      estimatedJsonBytes: new TextEncoder().encode(json).byteLength
+    };
+  }
+  /**
+   * Flush buffered data and log internal metrics summary.
+   */
+  async flush() {
+    this.#internalMetrics.flushCount++;
+    if (this.#config.logMetricsOnFlush) {
+      const metrics = this.getInternalMetrics();
+      const uptimeMs = Date.now() - metrics.startedAt.getTime();
+      const summary = [
+        `[TestExporter] flush #${metrics.flushCount} summary:`,
+        `  uptime: ${(uptimeMs / 1e3).toFixed(1)}s`,
+        `  total events received: ${metrics.totalEventsReceived}`,
+        `  by signal: tracing=${metrics.bySignal.tracing}, log=${metrics.bySignal.log}, metric=${metrics.bySignal.metric}, score=${metrics.bySignal.score}, feedback=${metrics.bySignal.feedback}`,
+        `  buffered: spans=${this.#spanStates.size}, logs=${this.#logEvents.length}, metrics=${this.#metricEvents.length}, scores=${this.#scoreEvents.length}, feedback=${this.#feedbackEvents.length}`,
+        `  estimated JSON size: ${(metrics.estimatedJsonBytes / 1024).toFixed(1)}KB`
+      ].join("\n");
+      this.logger.info(summary);
+    }
+  }
   async shutdown() {
-    this.logger.info("JsonExporter shutdown");
+    await this.flush();
+    this.logger.info("TestExporter shutdown");
   }
   // ============================================================================
   // Private Helpers
@@ -6921,6 +7211,634 @@ Run with { updateSnapshot: true } to update.`
     return Array.from(spanMap.values());
   }
 };
+var JsonExporter = TestExporter;
+var BaseObservabilityEventBus = class _BaseObservabilityEventBus extends base.MastraBase {
+  subscribers = /* @__PURE__ */ new Set();
+  /** In-flight async subscriber promises. Self-cleaning via .finally(). */
+  pendingSubscribers = /* @__PURE__ */ new Set();
+  constructor({ name } = {}) {
+    super({ component: logger.RegisteredLogger.OBSERVABILITY, name: name ?? "EventBus" });
+  }
+  /**
+   * Dispatch an event to all subscribers synchronously.
+   * Async handler promises are tracked internally and drained by {@link flush}.
+   *
+   * @param event - The event to broadcast to subscribers.
+   */
+  emit(event) {
+    for (const handler of this.subscribers) {
+      try {
+        const result = handler(event);
+        if (result && typeof result.then === "function") {
+          const promise = result.catch((err) => {
+            this.logger.error("[ObservabilityEventBus] Handler error:", err);
+          });
+          this.pendingSubscribers.add(promise);
+          void promise.finally(() => this.pendingSubscribers.delete(promise));
+        }
+      } catch (err) {
+        this.logger.error("[ObservabilityEventBus] Handler error:", err);
+      }
+    }
+  }
+  /**
+   * Register a handler to receive future events.
+   *
+   * @param handler - Callback invoked synchronously on each {@link emit}.
+   * @returns An unsubscribe function that removes the handler.
+   */
+  subscribe(handler) {
+    this.subscribers.add(handler);
+    return () => {
+      this.subscribers.delete(handler);
+    };
+  }
+  /** Max flush drain iterations before bailing — prevents infinite loops when handlers re-emit. */
+  static MAX_FLUSH_ITERATIONS = 3;
+  /** Await all in-flight async subscriber promises, draining until empty. */
+  async flush() {
+    let iterations = 0;
+    while (this.pendingSubscribers.size > 0) {
+      await Promise.allSettled([...this.pendingSubscribers]);
+      iterations++;
+      if (iterations >= _BaseObservabilityEventBus.MAX_FLUSH_ITERATIONS) {
+        this.logger.error(
+          `[ObservabilityEventBus] flush() exceeded ${_BaseObservabilityEventBus.MAX_FLUSH_ITERATIONS} drain iterations \u2014 ${this.pendingSubscribers.size} promises still pending. Handlers may be re-emitting during flush.`
+        );
+        break;
+      }
+    }
+  }
+  /** Flush pending promises, then clear all subscribers. */
+  async shutdown() {
+    await this.flush();
+    this.subscribers.clear();
+  }
+};
+var AutoExtractedMetrics = class {
+  /**
+   * @param observabilityBus - Bus used to emit derived MetricEvents.
+   * @param cardinalityFilter - Optional filter applied to metric labels before emission.
+   */
+  constructor(observabilityBus, cardinalityFilter) {
+    this.observabilityBus = observabilityBus;
+    this.cardinalityFilter = cardinalityFilter;
+  }
+  /**
+   * Route a tracing event to the appropriate span lifecycle handler.
+   * SPAN_STARTED increments a started counter; SPAN_ENDED emits ended counter,
+   * duration histogram, and (for model spans) token counters.
+   */
+  processTracingEvent(event) {
+    switch (event.type) {
+      case observability.TracingEventType.SPAN_STARTED:
+        this.onSpanStarted(event.exportedSpan);
+        break;
+      case observability.TracingEventType.SPAN_ENDED:
+        this.onSpanEnded(event.exportedSpan);
+        break;
+    }
+  }
+  /** Emit a `mastra_scores_total` counter for a score event. */
+  processScoreEvent(event) {
+    const labels = {
+      scorer: event.score.scorerName
+    };
+    if (event.score.metadata?.entityType) {
+      labels.entity_type = String(event.score.metadata.entityType);
+    }
+    if (event.score.experimentId) {
+      labels.experiment = event.score.experimentId;
+    }
+    this.emit("mastra_scores_total", "counter", 1, labels);
+  }
+  /** Emit a `mastra_feedback_total` counter for a feedback event. */
+  processFeedbackEvent(event) {
+    const labels = {
+      feedback_type: event.feedback.feedbackType,
+      source: event.feedback.source
+    };
+    if (event.feedback.metadata?.entityType) {
+      labels.entity_type = String(event.feedback.metadata.entityType);
+    }
+    if (event.feedback.experimentId) {
+      labels.experiment = event.feedback.experimentId;
+    }
+    this.emit("mastra_feedback_total", "counter", 1, labels);
+  }
+  /** Emit a started counter (e.g. `mastra_agent_runs_started`) for the span type. */
+  onSpanStarted(span) {
+    const labels = this.extractLabels(span);
+    const metricName = this.getStartedMetricName(span);
+    if (metricName) {
+      this.emit(metricName, "counter", 1, labels);
+    }
+  }
+  /** Emit ended counter, duration histogram, and token counters (for model spans). */
+  onSpanEnded(span) {
+    const labels = this.extractLabels(span);
+    const endedMetricName = this.getEndedMetricName(span);
+    if (endedMetricName) {
+      const endedLabels = { ...labels };
+      if (span.errorInfo) {
+        endedLabels.status = "error";
+      } else {
+        endedLabels.status = "ok";
+      }
+      this.emit(endedMetricName, "counter", 1, endedLabels);
+    }
+    const durationMetricName = this.getDurationMetricName(span);
+    if (durationMetricName && span.startTime && span.endTime) {
+      const durationMs = Math.max(0, span.endTime.getTime() - span.startTime.getTime());
+      const durationLabels = { ...labels };
+      if (span.errorInfo) {
+        durationLabels.status = "error";
+      } else {
+        durationLabels.status = "ok";
+      }
+      this.emit(durationMetricName, "histogram", durationMs, durationLabels);
+    }
+    if (span.type === observability.SpanType.MODEL_GENERATION) {
+      this.extractTokenMetrics(span, labels);
+    }
+  }
+  /** Build base metric labels from a span's entity and model attributes. */
+  extractLabels(span) {
+    const labels = {};
+    if (span.entityType) labels.entity_type = span.entityType;
+    const entityName = span.entityName ?? span.entityId;
+    if (entityName) labels.entity_name = entityName;
+    if (span.type === observability.SpanType.MODEL_GENERATION) {
+      const attrs = span.attributes;
+      if (attrs?.model) labels.model = String(attrs.model);
+      if (attrs?.provider) labels.provider = String(attrs.provider);
+    }
+    return labels;
+  }
+  /** Emit token usage counters from a MODEL_GENERATION span's `usage` attributes. Negative and non-finite values are skipped. */
+  extractTokenMetrics(span, labels) {
+    const attrs = span.attributes;
+    const usage = attrs?.usage;
+    if (!usage) return;
+    const inputTokens = Number(usage.inputTokens);
+    if (Number.isFinite(inputTokens) && inputTokens >= 0) {
+      this.emit("mastra_model_input_tokens", "counter", inputTokens, labels);
+    }
+    const outputTokens = Number(usage.outputTokens);
+    if (Number.isFinite(outputTokens) && outputTokens >= 0) {
+      this.emit("mastra_model_output_tokens", "counter", outputTokens, labels);
+    }
+    const inputDetails = usage.inputDetails;
+    const cacheRead = Number(inputDetails?.cacheRead);
+    if (Number.isFinite(cacheRead) && cacheRead >= 0) {
+      this.emit("mastra_model_cache_read_tokens", "counter", cacheRead, labels);
+    }
+    const cacheWrite = Number(inputDetails?.cacheWrite);
+    if (Number.isFinite(cacheWrite) && cacheWrite >= 0) {
+      this.emit("mastra_model_cache_write_tokens", "counter", cacheWrite, labels);
+    }
+  }
+  /** Map a span type to its `*_started` counter metric name, or `null` for unsupported types. */
+  getStartedMetricName(span) {
+    switch (span.type) {
+      case observability.SpanType.AGENT_RUN:
+        return "mastra_agent_runs_started";
+      case observability.SpanType.TOOL_CALL:
+        return "mastra_tool_calls_started";
+      case observability.SpanType.WORKFLOW_RUN:
+        return "mastra_workflow_runs_started";
+      case observability.SpanType.MODEL_GENERATION:
+        return "mastra_model_requests_started";
+      default:
+        return null;
+    }
+  }
+  /** Map a span type to its `*_ended` counter metric name, or `null` for unsupported types. */
+  getEndedMetricName(span) {
+    switch (span.type) {
+      case observability.SpanType.AGENT_RUN:
+        return "mastra_agent_runs_ended";
+      case observability.SpanType.TOOL_CALL:
+        return "mastra_tool_calls_ended";
+      case observability.SpanType.WORKFLOW_RUN:
+        return "mastra_workflow_runs_ended";
+      case observability.SpanType.MODEL_GENERATION:
+        return "mastra_model_requests_ended";
+      default:
+        return null;
+    }
+  }
+  /** Map a span type to its `*_duration_ms` histogram metric name, or `null` for unsupported types. */
+  getDurationMetricName(span) {
+    switch (span.type) {
+      case observability.SpanType.AGENT_RUN:
+        return "mastra_agent_duration_ms";
+      case observability.SpanType.TOOL_CALL:
+        return "mastra_tool_duration_ms";
+      case observability.SpanType.WORKFLOW_RUN:
+        return "mastra_workflow_duration_ms";
+      case observability.SpanType.MODEL_GENERATION:
+        return "mastra_model_duration_ms";
+      default:
+        return null;
+    }
+  }
+  /** Build an ExportedMetric, apply cardinality filtering, and emit it through the bus. */
+  emit(name, metricType, value, labels) {
+    const filteredLabels = this.cardinalityFilter ? this.cardinalityFilter.filterLabels(labels) : labels;
+    const exportedMetric = {
+      timestamp: /* @__PURE__ */ new Date(),
+      name,
+      metricType,
+      value,
+      labels: filteredLabels
+    };
+    const event = { type: "metric", metric: exportedMetric };
+    this.observabilityBus.emit(event);
+  }
+};
+function routeToHandler(handler, event, logger) {
+  try {
+    switch (event.type) {
+      case observability.TracingEventType.SPAN_STARTED:
+      case observability.TracingEventType.SPAN_UPDATED:
+      case observability.TracingEventType.SPAN_ENDED: {
+        const fn = handler.onTracingEvent ? handler.onTracingEvent.bind(handler) : handler.exportTracingEvent.bind(handler);
+        return catchAsyncResult(fn(event), handler.name, "tracing", logger);
+      }
+      case "log":
+        if (handler.onLogEvent) {
+          return catchAsyncResult(handler.onLogEvent(event), handler.name, "log", logger);
+        }
+        break;
+      case "metric":
+        if (handler.onMetricEvent) {
+          return catchAsyncResult(handler.onMetricEvent(event), handler.name, "metric", logger);
+        }
+        break;
+      case "score":
+        if (handler.onScoreEvent) {
+          return catchAsyncResult(handler.onScoreEvent(event), handler.name, "score", logger);
+        }
+        break;
+      case "feedback":
+        if (handler.onFeedbackEvent) {
+          return catchAsyncResult(handler.onFeedbackEvent(event), handler.name, "feedback", logger);
+        }
+        break;
+    }
+  } catch (err) {
+    logger.error(`[Observability] Handler error [handler=${handler.name}]:`, err);
+  }
+}
+function catchAsyncResult(result, handlerName, signal, logger) {
+  if (result && typeof result.then === "function") {
+    return result.catch((err) => {
+      logger.error(`[Observability] ${signal} handler error [handler=${handlerName}]:`, err);
+    });
+  }
+}
+
+// src/bus/observability-bus.ts
+var MAX_FLUSH_ITERATIONS = 3;
+function isTracingEvent(event) {
+  return event.type === observability.TracingEventType.SPAN_STARTED || event.type === observability.TracingEventType.SPAN_UPDATED || event.type === observability.TracingEventType.SPAN_ENDED;
+}
+var ObservabilityBus = class extends BaseObservabilityEventBus {
+  exporters = [];
+  bridge;
+  autoExtractor;
+  /** In-flight handler promises from routeToHandler. Self-cleaning via .finally(). */
+  pendingHandlers = /* @__PURE__ */ new Set();
+  constructor() {
+    super({ name: "ObservabilityBus" });
+  }
+  /**
+   * Enable auto-extraction of metrics from tracing, score, and feedback events.
+   * When enabled, span lifecycle events automatically generate counter/histogram
+   * metrics (e.g., mastra_agent_runs_started, mastra_model_duration_ms).
+   *
+   * No-ops if auto-extraction is already enabled.
+   *
+   * @param cardinalityFilter - Optional filter applied to auto-extracted metric labels.
+   */
+  enableAutoExtractedMetrics(cardinalityFilter) {
+    if (this.autoExtractor) {
+      return;
+    }
+    this.autoExtractor = new AutoExtractedMetrics(this, cardinalityFilter);
+  }
+  /**
+   * Register an exporter to receive routed events.
+   * Duplicate registrations (same instance) are silently ignored.
+   *
+   * @param exporter - The exporter to register.
+   */
+  registerExporter(exporter) {
+    if (this.exporters.includes(exporter)) {
+      return;
+    }
+    this.exporters.push(exporter);
+  }
+  /**
+   * Unregister an exporter.
+   *
+   * @param exporter - The exporter instance to remove.
+   * @returns `true` if the exporter was found and removed, `false` otherwise.
+   */
+  unregisterExporter(exporter) {
+    const index = this.exporters.indexOf(exporter);
+    if (index !== -1) {
+      this.exporters.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get registered exporters (read-only snapshot).
+   */
+  getExporters() {
+    return [...this.exporters];
+  }
+  /**
+   * Register a bridge to receive all routed events alongside exporters.
+   * Only one bridge can be registered at a time; replacing an existing bridge
+   * logs a warning.
+   *
+   * @param bridge - The bridge to register.
+   */
+  registerBridge(bridge) {
+    if (this.bridge) {
+      this.logger.warn(`[ObservabilityBus] Replacing existing bridge with new bridge`);
+    }
+    this.bridge = bridge;
+  }
+  /**
+   * Unregister the bridge.
+   *
+   * @returns `true` if a bridge was registered and removed, `false` otherwise.
+   */
+  unregisterBridge() {
+    if (this.bridge) {
+      this.bridge = void 0;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get the registered bridge, if any.
+   */
+  getBridge() {
+    return this.bridge;
+  }
+  /**
+   * Emit an event: route to exporter/bridge handlers, run auto-extraction,
+   * then forward to base class for subscriber delivery.
+   *
+   * emit() is synchronous — async handler promises are tracked internally
+   * and can be drained via flush().
+   */
+  emit(event) {
+    for (const exporter of this.exporters) {
+      this.trackPromise(routeToHandler(exporter, event, this.logger));
+    }
+    if (this.bridge) {
+      this.trackPromise(routeToHandler(this.bridge, event, this.logger));
+    }
+    if (this.autoExtractor) {
+      try {
+        if (isTracingEvent(event)) {
+          this.autoExtractor.processTracingEvent(event);
+        } else if (event.type === "score") {
+          this.autoExtractor.processScoreEvent(event);
+        } else if (event.type === "feedback") {
+          this.autoExtractor.processFeedbackEvent(event);
+        }
+      } catch (err) {
+        this.logger.error("[ObservabilityBus] Auto-extraction error:", err);
+      }
+    }
+    super.emit(event);
+  }
+  /**
+   * Track an async handler promise so flush() can await it.
+   * No-ops for sync (void) results.
+   */
+  trackPromise(result) {
+    if (result && typeof result.then === "function") {
+      const promise = result;
+      this.pendingHandlers.add(promise);
+      void promise.finally(() => this.pendingHandlers.delete(promise));
+    }
+  }
+  /**
+   * Two-phase flush to ensure all observability data is fully exported.
+   *
+   * **Phase 1 — Delivery:** Await all in-flight handler promises (exporters,
+   * bridge, and base-class subscribers). After this resolves, all event data
+   * has been delivered to handler methods.
+   *
+   * **Phase 2 — Buffer drain:** Call flush() on each exporter and bridge to
+   * drain their SDK-internal buffers (e.g., OTEL BatchSpanProcessor, Langfuse
+   * client queue). Phases are sequential — Phase 2 must not start until
+   * Phase 1 completes, otherwise exporters would flush empty buffers.
+   */
+  async flush() {
+    let iterations = 0;
+    while (this.pendingHandlers.size > 0) {
+      await Promise.allSettled([...this.pendingHandlers]);
+      iterations++;
+      if (iterations >= MAX_FLUSH_ITERATIONS) {
+        this.logger.error(
+          `[ObservabilityBus] flush() exceeded ${MAX_FLUSH_ITERATIONS} drain iterations \u2014 ${this.pendingHandlers.size} promises still pending. Handlers may be re-emitting during flush.`
+        );
+        if (this.pendingHandlers.size > 0) {
+          await Promise.allSettled([...this.pendingHandlers]);
+        }
+        break;
+      }
+    }
+    await super.flush();
+    const bufferFlushPromises = this.exporters.map((e) => e.flush());
+    if (this.bridge) {
+      bufferFlushPromises.push(this.bridge.flush());
+    }
+    if (bufferFlushPromises.length > 0) {
+      await Promise.allSettled(bufferFlushPromises);
+    }
+  }
+  /** Flush all pending events and exporter buffers, then clear subscribers. */
+  async shutdown() {
+    await this.flush();
+    await super.shutdown();
+  }
+};
+
+// src/context/logger.ts
+var LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4
+};
+var LoggerContextImpl = class {
+  config;
+  /**
+   * Create a logger context. Tags and metadata are defensively copied so
+   * mutations after construction do not affect emitted logs.
+   */
+  constructor(config) {
+    this.config = {
+      ...config,
+      tags: config.tags ? [...config.tags] : void 0,
+      metadata: config.metadata ? structuredClone(config.metadata) : void 0
+    };
+  }
+  /** Log at DEBUG level. */
+  debug(message, data) {
+    this.log("debug", message, data);
+  }
+  /** Log at INFO level. */
+  info(message, data) {
+    this.log("info", message, data);
+  }
+  /** Log at WARN level. */
+  warn(message, data) {
+    this.log("warn", message, data);
+  }
+  /** Log at ERROR level. */
+  error(message, data) {
+    this.log("error", message, data);
+  }
+  /** Log at FATAL level. */
+  fatal(message, data) {
+    this.log("fatal", message, data);
+  }
+  /**
+   * Build an ExportedLog, check against the minimum level, and emit it through the bus.
+   */
+  log(level, message, data) {
+    const minLevel = this.config.minLevel ?? "debug";
+    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[minLevel]) {
+      return;
+    }
+    const exportedLog = {
+      timestamp: /* @__PURE__ */ new Date(),
+      level,
+      message,
+      data,
+      traceId: this.config.traceId,
+      spanId: this.config.spanId,
+      tags: this.config.tags,
+      metadata: this.config.metadata
+    };
+    const event = { type: "log", log: exportedLog };
+    this.config.observabilityBus.emit(event);
+  }
+};
+
+// src/context/metrics.ts
+var MetricsContextImpl = class {
+  config;
+  /**
+   * Create a metrics context. Base labels are defensively copied so
+   * mutations after construction do not affect emitted metrics.
+   */
+  constructor(config) {
+    this.config = {
+      ...config,
+      labels: config.labels ? { ...config.labels } : void 0
+    };
+  }
+  /**
+   * Create a counter instrument. Call `.add(value)` to increment.
+   *
+   * @param name - Metric name (e.g. `mastra_custom_requests_total`).
+   */
+  counter(name) {
+    return {
+      add: (value, additionalLabels) => {
+        this.emit(name, "counter", value, additionalLabels);
+      }
+    };
+  }
+  /**
+   * Create a gauge instrument. Call `.set(value)` to record a point-in-time value.
+   *
+   * @param name - Metric name (e.g. `mastra_queue_depth`).
+   */
+  gauge(name) {
+    return {
+      set: (value, additionalLabels) => {
+        this.emit(name, "gauge", value, additionalLabels);
+      }
+    };
+  }
+  /**
+   * Create a histogram instrument. Call `.record(value)` to observe a measurement.
+   *
+   * @param name - Metric name (e.g. `mastra_request_duration_ms`).
+   */
+  histogram(name) {
+    return {
+      record: (value, additionalLabels) => {
+        this.emit(name, "histogram", value, additionalLabels);
+      }
+    };
+  }
+  /** Merge base + additional labels, apply cardinality filtering, and emit a MetricEvent. Non-finite values are silently dropped. */
+  emit(name, metricType, value, additionalLabels) {
+    if (!Number.isFinite(value)) return;
+    const allLabels = {
+      ...this.config.labels,
+      ...additionalLabels
+    };
+    const filteredLabels = this.config.cardinalityFilter.filterLabels(allLabels);
+    const exportedMetric = {
+      timestamp: /* @__PURE__ */ new Date(),
+      name,
+      metricType,
+      value,
+      labels: filteredLabels
+    };
+    const event = { type: "metric", metric: exportedMetric };
+    this.config.observabilityBus.emit(event);
+  }
+};
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var CardinalityFilter = class {
+  blockedLabels;
+  blockUUIDs;
+  /**
+   * @param config - Optional configuration. When omitted, uses
+   *   {@link DEFAULT_BLOCKED_LABELS} and blocks UUID-valued labels.
+   */
+  constructor(config) {
+    const blocked = config?.blockedLabels ?? [...observability.DEFAULT_BLOCKED_LABELS];
+    this.blockedLabels = new Set(blocked.map((l) => l.toLowerCase()));
+    this.blockUUIDs = config?.blockUUIDs ?? true;
+  }
+  /**
+   * Return a copy of `labels` with blocked keys and UUID values removed.
+   *
+   * @param labels - Raw metric labels to filter.
+   * @returns A new object containing only the allowed labels.
+   */
+  filterLabels(labels) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(labels)) {
+      if (this.blockedLabels.has(key.toLowerCase())) {
+        continue;
+      }
+      if (this.blockUUIDs && UUID_REGEX.test(value)) {
+        continue;
+      }
+      filtered[key] = value;
+    }
+    return filtered;
+  }
+};
 
 // src/usage.ts
 function extractUsageMetrics(usage, providerMetadata) {
@@ -7943,6 +8861,15 @@ var NoOpSpan = class extends BaseSpan {
 // src/instances/base.ts
 var BaseObservabilityInstance = class extends base.MastraBase {
   config;
+  /**
+   * Unified event bus for all observability signals.
+   * Routes events to registered exporters based on event type.
+   */
+  observabilityBus;
+  /**
+   * Cardinality filter for metrics label protection.
+   */
+  cardinalityFilter;
   constructor(config) {
     super({ component: logger.RegisteredLogger.OBSERVABILITY, name: config.serviceName });
     this.config = {
@@ -7956,6 +8883,15 @@ var BaseObservabilityInstance = class extends base.MastraBase {
       requestContextKeys: config.requestContextKeys ?? [],
       serializationOptions: config.serializationOptions
     };
+    this.cardinalityFilter = new CardinalityFilter();
+    this.observabilityBus = new ObservabilityBus();
+    for (const exporter of this.exporters) {
+      this.observabilityBus.registerExporter(exporter);
+    }
+    if (this.config.bridge) {
+      this.observabilityBus.registerBridge(this.config.bridge);
+    }
+    this.observabilityBus.enableAutoExtractedMetrics(this.cardinalityFilter);
     if (this.config.bridge?.init) {
       this.config.bridge.init({ config: this.config });
     }
@@ -8108,6 +9044,108 @@ var BaseObservabilityInstance = class extends base.MastraBase {
   getLogger() {
     return this.logger;
   }
+  /**
+   * Get the ObservabilityBus for this instance.
+   * The bus routes all observability events (tracing, logs, metrics, scores, feedback)
+   * to registered exporters based on event type.
+   */
+  getObservabilityBus() {
+    return this.observabilityBus;
+  }
+  // ============================================================================
+  // Context-factory bridge methods
+  // ============================================================================
+  /**
+   * Extract entity context labels from a span's entity hierarchy by
+   * walking the parent chain.
+   *
+   * Returns labels for: entity_type/name, parent_type/name, root_type/name.
+   * Internal spans are skipped when resolving parent and root entities.
+   */
+  extractEntityLabels(span) {
+    const labels = {};
+    if (span.entityType) labels.entity_type = span.entityType;
+    if (span.entityName) labels.entity_name = span.entityName;
+    let parentSpan = span.parent;
+    while (parentSpan && parentSpan.isInternal) {
+      parentSpan = parentSpan.parent;
+    }
+    if (parentSpan?.entityType && parentSpan.entityName) {
+      labels.parent_type = parentSpan.entityType;
+      labels.parent_name = parentSpan.entityName;
+      let rootEntity = parentSpan;
+      let current = parentSpan.parent;
+      while (current) {
+        if (!current.isInternal && current.entityType && current.entityName) {
+          rootEntity = current;
+        }
+        current = current.parent;
+      }
+      if (rootEntity !== parentSpan) {
+        labels.root_type = rootEntity.entityType;
+        labels.root_name = rootEntity.entityName;
+      }
+    }
+    return labels;
+  }
+  /**
+   * Resolve tags for a span. Uses the span's own tags if present,
+   * otherwise walks to the root span to inherit its tags.
+   */
+  resolveSpanTags(span) {
+    if (span.tags) return span.tags;
+    let root = span;
+    while (root.parent) {
+      root = root.parent;
+    }
+    return root.tags;
+  }
+  /**
+   * Get a LoggerContext correlated to a span.
+   * Called by the context-factory in core (deriveLoggerContext) so that
+   * `observabilityContext.loggerVNext` is a real logger instead of no-op.
+   */
+  getLoggerContext(span) {
+    const entityLabels = span ? this.extractEntityLabels(span) : void 0;
+    const hasEntityLabels = entityLabels && Object.keys(entityLabels).length > 0;
+    const metadata = hasEntityLabels || span?.metadata || this.config.serviceName ? {
+      ...hasEntityLabels ? entityLabels : void 0,
+      ...span?.metadata,
+      ...this.config.serviceName ? { serviceName: this.config.serviceName } : void 0
+    } : void 0;
+    return new LoggerContextImpl({
+      traceId: span?.traceId,
+      spanId: span?.id,
+      tags: span ? this.resolveSpanTags(span) : void 0,
+      metadata,
+      observabilityBus: this.observabilityBus
+    });
+  }
+  /**
+   * Get a MetricsContext, optionally tagged from a span's entity info.
+   * Called by the context-factory in core (deriveMetricsContext) so that
+   * `observabilityContext.metrics` is a real metrics context instead of no-op.
+   */
+  getMetricsContext(span) {
+    const labels = span ? this.extractEntityLabels(span) : {};
+    const attrs = span?.attributes;
+    if (attrs?.model && typeof attrs.model === "string") labels.model = attrs.model;
+    if (attrs?.provider && typeof attrs.provider === "string") labels.provider = attrs.provider;
+    if (this.config.serviceName) labels.service_name = this.config.serviceName;
+    return new MetricsContextImpl({
+      labels: Object.keys(labels).length > 0 ? labels : void 0,
+      observabilityBus: this.observabilityBus,
+      cardinalityFilter: this.cardinalityFilter
+    });
+  }
+  /**
+   * Emit any observability event through the bus.
+   * The bus routes the event to the appropriate handler on each registered exporter,
+   * and for tracing events triggers auto-extracted metrics.
+   */
+  emitObservabilityEvent(event) {
+    this.observabilityBus.emit(event);
+  }
   // ============================================================================
   // Span Lifecycle Management
   // ============================================================================
@@ -8251,40 +9289,56 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     return processedSpan?.exportSpan(this.config.includeInternalSpans);
   }
   /**
-   * Emit a span started event
+   * Emit a span started event.
+   * Routes through the ObservabilityBus so exporters receive it via onTracingEvent
+   * and auto-extracted metrics are generated.
    */
   emitSpanStarted(span) {
     const exportedSpan = this.getSpanForExport(span);
     if (exportedSpan) {
-      this.exportTracingEvent({ type: observability.TracingEventType.SPAN_STARTED, exportedSpan }).catch((error) => {
-        this.logger.error("[Observability] Failed to export span_started event", error);
-      });
+      const event = { type: observability.TracingEventType.SPAN_STARTED, exportedSpan };
+      this.emitTracingEvent(event);
     }
   }
   /**
-   * Emit a span ended event (called automatically when spans end)
+   * Emit a span ended event (called automatically when spans end).
+   * Routes through the ObservabilityBus so exporters receive it via onTracingEvent
+   * and auto-extracted metrics are generated.
    */
   emitSpanEnded(span) {
     const exportedSpan = this.getSpanForExport(span);
     if (exportedSpan) {
-      this.exportTracingEvent({ type: observability.TracingEventType.SPAN_ENDED, exportedSpan }).catch((error) => {
-        this.logger.error("[Observability] Failed to export span_ended event", error);
-      });
+      const event = { type: observability.TracingEventType.SPAN_ENDED, exportedSpan };
+      this.emitTracingEvent(event);
     }
   }
   /**
-   * Emit a span updated event
+   * Emit a span updated event.
+   * Routes through the ObservabilityBus so exporters receive it via onTracingEvent
+   * and auto-extracted metrics are generated.
    */
   emitSpanUpdated(span) {
     const exportedSpan = this.getSpanForExport(span);
     if (exportedSpan) {
-      this.exportTracingEvent({ type: observability.TracingEventType.SPAN_UPDATED, exportedSpan }).catch((error) => {
-        this.logger.error("[Observability] Failed to export span_updated event", error);
-      });
+      const event = { type: observability.TracingEventType.SPAN_UPDATED, exportedSpan };
+      this.emitTracingEvent(event);
     }
   }
   /**
-   * Export tracing event through all exporters and bridge (realtime mode)
+   * Emit a tracing event through the bus.
+   *
+   * The bus routes the event to each registered exporter's and bridge's
+   * onTracingEvent handler and triggers auto-extracted metrics (e.g.,
+   * mastra_agent_runs_started, mastra_model_duration_ms).
+   */
+  emitTracingEvent(event) {
+    this.observabilityBus.emit(event);
+  }
+  /**
+   * Export tracing event through all exporters and bridge.
+   *
+   * @deprecated Prefer emitTracingEvent() which routes through the bus.
+   * Kept for backward compatibility with subclasses that may override it.
    */
   async exportTracingEvent(event) {
     const targets = [
@@ -8314,26 +9368,18 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     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.
+   * Flush all observability data: awaits in-flight handler promises, then
+   * drains exporter and bridge SDK-internal buffers.
+   *
+   * Delegates to ObservabilityBus.flush() which owns the two-phase logic.
    *
-   * 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.
+   * This is critical for durable execution engines (e.g., Inngest) where
+   * the process may be interrupted after a step completes. Calling flush()
+   * outside the durable step ensures all span data reaches external systems.
    */
   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);
-      }
-    });
+    await this.observabilityBus.flush();
     this.logger.debug(`[Observability] Flush completed [name=${this.name}]`);
   }
   /**
@@ -8341,6 +9387,7 @@ var BaseObservabilityInstance = class extends base.MastraBase {
    */
   async shutdown() {
     this.logger.debug(`[Observability] Shutdown started [name=${this.name}]`);
+    await this.observabilityBus.shutdown();
     const shutdownPromises = [
       ...this.exporters.map((e) => e.shutdown()),
       ...this.spanOutputProcessors.map((p) => p.shutdown())
@@ -8348,7 +9395,14 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     if (this.config.bridge) {
       shutdownPromises.push(this.config.bridge.shutdown());
     }
-    await Promise.allSettled(shutdownPromises);
+    if (shutdownPromises.length > 0) {
+      const results = await Promise.allSettled(shutdownPromises);
+      for (const result of results) {
+        if (result.status === "rejected") {
+          this.logger.error(`[Observability] Component shutdown failed [name=${this.name}]:`, result.reason);
+        }
+      }
+    }
     this.logger.info(`[Observability] Shutdown completed [name=${this.name}]`);
   }
 };
@@ -8735,9 +9789,12 @@ function buildTracingOptions(...updaters) {
   return updaters.reduce((opts, updater) => updater(opts), {});
 }
 
+exports.AutoExtractedMetrics = AutoExtractedMetrics;
 exports.BaseExporter = BaseExporter;
+exports.BaseObservabilityEventBus = BaseObservabilityEventBus;
 exports.BaseObservabilityInstance = BaseObservabilityInstance;
 exports.BaseSpan = BaseSpan;
+exports.CardinalityFilter = CardinalityFilter;
 exports.CloudExporter = CloudExporter;
 exports.ConsoleExporter = ConsoleExporter;
 exports.DEFAULT_DEEP_CLEAN_OPTIONS = DEFAULT_DEEP_CLEAN_OPTIONS;
@@ -8746,9 +9803,12 @@ exports.DefaultExporter = DefaultExporter;
 exports.DefaultObservabilityInstance = DefaultObservabilityInstance;
 exports.DefaultSpan = DefaultSpan;
 exports.JsonExporter = JsonExporter;
+exports.LoggerContextImpl = LoggerContextImpl;
+exports.MetricsContextImpl = MetricsContextImpl;
 exports.ModelSpanTracker = ModelSpanTracker;
 exports.NoOpSpan = NoOpSpan;
 exports.Observability = Observability;
+exports.ObservabilityBus = ObservabilityBus;
 exports.SamplingStrategyType = SamplingStrategyType;
 exports.SensitiveDataFilter = SensitiveDataFilter;
 exports.TestExporter = TestExporter;
@@ -8762,6 +9822,7 @@ exports.mergeSerializationOptions = mergeSerializationOptions;
 exports.observabilityConfigValueSchema = observabilityConfigValueSchema;
 exports.observabilityInstanceConfigSchema = observabilityInstanceConfigSchema;
 exports.observabilityRegistryConfigSchema = observabilityRegistryConfigSchema;
+exports.routeToHandler = routeToHandler;
 exports.samplingStrategySchema = samplingStrategySchema;
 exports.serializationOptionsSchema = serializationOptionsSchema;
 exports.truncateString = truncateString;