@mastra/observability 1.6.0-alpha.2 → 1.6.0

package/dist/index.cjs

@@ -22,6 +22,47 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
+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);
+    });
+  }
+}
 
 // ../../node_modules/.pnpm/zod@4.3.6/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -15901,7 +15942,7 @@ var TestExporter = class extends BaseExporter {
     this.#trackEvent("log");
     if (this.#config.storeLogs) {
       const log = event.log;
-      const traceId = log.correlationContext?.traceId;
+      const traceId = log.traceId;
       const logMessage = `[TestExporter] log.${log.level}: "${log.message}"${traceId ? ` (trace: ${traceId.slice(-8)})` : ""}`;
       this.#debugLogs.push(logMessage);
     }
@@ -16019,7 +16060,7 @@ var TestExporter = class extends BaseExporter {
   getByTraceId(traceId) {
     const events = this.#tracingEvents.filter((e) => e.exportedSpan.traceId === traceId);
     const spans = this.#getUniqueSpansFromEvents(events);
-    const logs = this.#logEvents.filter((e) => e.log.correlationContext?.traceId === traceId).map((e) => e.log);
+    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 };
@@ -16086,7 +16127,7 @@ var TestExporter = class extends BaseExporter {
       traceIds.add(event.exportedSpan.traceId);
     }
     for (const event of this.#logEvents) {
-      if (event.log.correlationContext?.traceId) traceIds.add(event.log.correlationContext.traceId);
+      if (event.log.traceId) traceIds.add(event.log.traceId);
     }
     for (const event of this.#scoreEvents) {
       traceIds.add(event.score.traceId);
@@ -16121,7 +16162,7 @@ var TestExporter = class extends BaseExporter {
    * Get logs for a specific trace
    */
   getLogsByTraceId(traceId) {
-    return this.#logEvents.filter((e) => e.log.correlationContext?.traceId === traceId).map((e) => e.log);
+    return this.#logEvents.filter((e) => e.log.traceId === traceId).map((e) => e.log);
   }
   // ============================================================================
   // Metric Query Methods
@@ -16995,47 +17036,6 @@ var BaseObservabilityEventBus = class _BaseObservabilityEventBus extends base.Ma
     this.subscribers.clear();
   }
 };
-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;
@@ -17195,9 +17195,12 @@ var LoggerContextImpl = class {
    * mutations after construction do not affect emitted logs.
    */
   constructor(config2) {
+    const correlationContext = config2.correlationContext ? { ...config2.correlationContext } : void 0;
     this.config = {
       ...config2,
-      correlationContext: config2.correlationContext ? { ...config2.correlationContext } : void 0,
+      traceId: config2.traceId ?? correlationContext?.traceId,
+      spanId: config2.spanId ?? correlationContext?.spanId,
+      correlationContext,
       metadata: config2.metadata ? structuredClone(config2.metadata) : void 0
     };
   }
@@ -17234,6 +17237,8 @@ var LoggerContextImpl = class {
       level,
       message,
       data,
+      traceId: this.config.traceId,
+      spanId: this.config.spanId,
       correlationContext: this.config.correlationContext,
       metadata: this.config.metadata
     };
@@ -17244,6 +17249,8 @@ var LoggerContextImpl = class {
 
 // src/context/metrics.ts
 var MetricsContextImpl = class {
+  traceId;
+  spanId;
   correlationContext;
   metadata;
   cardinalityFilter;
@@ -17254,6 +17261,8 @@ var MetricsContextImpl = class {
    */
   constructor(config2) {
     this.correlationContext = config2.correlationContext ? { ...config2.correlationContext } : void 0;
+    this.traceId = config2.traceId ?? this.correlationContext?.traceId;
+    this.spanId = config2.spanId ?? this.correlationContext?.spanId;
     this.metadata = config2.metadata ? structuredClone(config2.metadata) : void 0;
     this.cardinalityFilter = config2.cardinalityFilter;
     this.observabilityBus = config2.observabilityBus;
@@ -17267,6 +17276,8 @@ var MetricsContextImpl = class {
     const costContext = options?.costContext ? cloneCostContext(options.costContext) : void 0;
     const exportedMetric = {
       timestamp: /* @__PURE__ */ new Date(),
+      traceId: this.traceId,
+      spanId: this.spanId,
       name,
       value,
       labels: filteredLabels,
@@ -19201,6 +19212,8 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     const correlationContext = span?.getCorrelationContext?.();
     const metadata = span?.metadata ? structuredClone(span.metadata) : void 0;
     return new LoggerContextImpl({
+      traceId: span?.traceId,
+      spanId: span?.id,
       correlationContext,
       metadata,
       observabilityBus: this.observabilityBus
@@ -19215,6 +19228,8 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     const correlationContext = span?.getCorrelationContext?.();
     const metadata = span?.metadata ? structuredClone(span.metadata) : void 0;
     return new MetricsContextImpl({
+      traceId: span?.traceId,
+      spanId: span?.id,
       correlationContext,
       metadata,
       cardinalityFilter: this.cardinalityFilter,
@@ -19229,6 +19244,13 @@ var BaseObservabilityInstance = class extends base.MastraBase {
   emitObservabilityEvent(event) {
     this.observabilityBus.emit(event);
   }
+  /**
+   * Internal hook used by RecordedTrace/RecordedSpan hydration to route
+   * non-tracing annotation events back through the normal exporter pipeline.
+   */
+  __emitRecordedEvent(event) {
+    this.emitObservabilityEvent(event);
+  }
   // ============================================================================
   // Span Lifecycle Management
   // ============================================================================
@@ -19503,6 +19525,311 @@ var DefaultObservabilityInstance = class extends BaseObservabilityInstance {
   }
 };
 
+// src/recorded.ts
+function nullToUndefined(value) {
+  return value ?? void 0;
+}
+function mergeMetadata(base, extra) {
+  if (!base && !extra) return void 0;
+  return {
+    ...base ?? {},
+    ...extra ?? {}
+  };
+}
+function normalizeErrorInfo(error48) {
+  if (!error48 || typeof error48 !== "object" || !("message" in error48) || typeof error48.message !== "string") {
+    return void 0;
+  }
+  return {
+    message: error48.message,
+    id: "id" in error48 && typeof error48.id === "string" ? error48.id : void 0,
+    domain: "domain" in error48 && typeof error48.domain === "string" ? error48.domain : void 0,
+    category: "category" in error48 && typeof error48.category === "string" ? error48.category : void 0,
+    details: "details" in error48 && error48.details && typeof error48.details === "object" ? error48.details : void 0
+  };
+}
+function buildCorrelationContext(span, rootSpan, parent) {
+  return {
+    tags: rootSpan.tags ?? void 0,
+    entityType: nullToUndefined(span.entityType),
+    entityId: nullToUndefined(span.entityId),
+    entityName: nullToUndefined(span.entityName),
+    parentEntityType: parent?.entityType ?? void 0,
+    parentEntityId: parent?.entityId ?? void 0,
+    parentEntityName: parent?.entityName ?? void 0,
+    rootEntityType: nullToUndefined(rootSpan.entityType),
+    rootEntityId: nullToUndefined(rootSpan.entityId),
+    rootEntityName: nullToUndefined(rootSpan.entityName),
+    userId: nullToUndefined(span.userId),
+    organizationId: nullToUndefined(span.organizationId),
+    resourceId: nullToUndefined(span.resourceId),
+    runId: nullToUndefined(span.runId),
+    sessionId: nullToUndefined(span.sessionId),
+    threadId: nullToUndefined(span.threadId),
+    requestId: nullToUndefined(span.requestId),
+    environment: nullToUndefined(span.environment),
+    source: nullToUndefined(span.source),
+    serviceName: nullToUndefined(span.serviceName),
+    experimentId: nullToUndefined(span.experimentId)
+  };
+}
+function buildRecordedScoreEvent(args) {
+  const { span, rootSpan, parent, score, spanId } = args;
+  return {
+    type: "score",
+    score: {
+      timestamp: /* @__PURE__ */ new Date(),
+      traceId: span.traceId,
+      spanId,
+      scorerId: score.scorerId,
+      scorerVersion: score.scorerVersion,
+      source: score.source,
+      scoreSource: score.scoreSource,
+      score: score.score,
+      reason: score.reason,
+      experimentId: score.experimentId,
+      scoreTraceId: score.scoreTraceId,
+      correlationContext: buildCorrelationContext(span, rootSpan, parent),
+      metadata: mergeMetadata(span.metadata, score.metadata)
+    }
+  };
+}
+function buildRecordedFeedbackEvent(args) {
+  const { span, rootSpan, parent, feedback, spanId } = args;
+  return {
+    type: "feedback",
+    feedback: {
+      timestamp: /* @__PURE__ */ new Date(),
+      traceId: span.traceId,
+      spanId,
+      source: feedback.source,
+      feedbackSource: feedback.feedbackSource,
+      feedbackType: feedback.feedbackType,
+      value: feedback.value,
+      userId: feedback.userId,
+      feedbackUserId: feedback.feedbackUserId,
+      comment: feedback.comment,
+      sourceId: feedback.sourceId,
+      experimentId: feedback.experimentId,
+      correlationContext: buildCorrelationContext(span, rootSpan, parent),
+      metadata: mergeMetadata(span.metadata, feedback.metadata)
+    }
+  };
+}
+function findSpanById(spans, spanId) {
+  if (!spanId) return void 0;
+  return spans.find((span) => span.spanId === spanId);
+}
+function buildRecordedScoreEventFromTrace(args) {
+  const rootSpan = findRootSpan(args.trace.spans);
+  if (!rootSpan) return null;
+  const span = args.spanId ? findSpanById(args.trace.spans, args.spanId) : rootSpan;
+  if (!span) return null;
+  const parent = span.parentSpanId ? findSpanById(args.trace.spans, span.parentSpanId) : void 0;
+  return buildRecordedScoreEvent({
+    span,
+    rootSpan,
+    parent,
+    score: args.score,
+    spanId: args.spanId
+  });
+}
+function buildRecordedFeedbackEventFromTrace(args) {
+  const rootSpan = findRootSpan(args.trace.spans);
+  if (!rootSpan) return null;
+  const span = args.spanId ? findSpanById(args.trace.spans, args.spanId) : rootSpan;
+  if (!span) return null;
+  const parent = span.parentSpanId ? findSpanById(args.trace.spans, span.parentSpanId) : void 0;
+  return buildRecordedFeedbackEvent({
+    span,
+    rootSpan,
+    parent,
+    feedback: args.feedback,
+    spanId: args.spanId
+  });
+}
+var RecordedSpanImpl = class {
+  id;
+  traceId;
+  name;
+  type;
+  entityType;
+  entityId;
+  entityName;
+  startTime;
+  endTime;
+  attributes;
+  metadata;
+  tags;
+  input;
+  output;
+  errorInfo;
+  requestContext;
+  isEvent;
+  isRootSpan;
+  parentSpanId;
+  parent;
+  children = [];
+  #raw;
+  #rootSpan;
+  #emitRecordedEvent;
+  #canEmitRecordedEvent;
+  #debugRecordedAnnotationUnavailable;
+  constructor(args) {
+    const { raw, rootSpan, emitRecordedEvent, canEmitRecordedEvent, debugRecordedAnnotationUnavailable } = args;
+    this.#raw = raw;
+    this.#rootSpan = rootSpan;
+    this.#emitRecordedEvent = emitRecordedEvent;
+    this.#canEmitRecordedEvent = canEmitRecordedEvent;
+    this.#debugRecordedAnnotationUnavailable = debugRecordedAnnotationUnavailable;
+    this.id = raw.spanId;
+    this.traceId = raw.traceId;
+    this.name = raw.name;
+    this.type = raw.spanType;
+    this.entityType = raw.entityType ?? void 0;
+    this.entityId = raw.entityId ?? void 0;
+    this.entityName = raw.entityName ?? void 0;
+    this.startTime = raw.startedAt;
+    this.endTime = raw.endedAt ?? void 0;
+    this.attributes = raw.attributes ?? void 0;
+    this.metadata = raw.metadata ?? void 0;
+    this.tags = raw.tags ?? void 0;
+    this.input = raw.input ?? void 0;
+    this.output = raw.output ?? void 0;
+    this.errorInfo = normalizeErrorInfo(raw.error);
+    this.requestContext = raw.requestContext ?? void 0;
+    this.isEvent = raw.isEvent;
+    this.isRootSpan = !raw.parentSpanId;
+    this.parentSpanId = raw.parentSpanId ?? void 0;
+  }
+  async addScore(score) {
+    if (!this.#canEmitRecordedEvent()) {
+      this.#debugRecordedAnnotationUnavailable({ kind: "score", traceId: this.traceId, spanId: this.id });
+      return;
+    }
+    await this.#emitRecordedEvent(
+      buildRecordedScoreEvent({
+        span: this.#raw,
+        rootSpan: this.#rootSpan,
+        parent: this.parent,
+        score,
+        spanId: this.id
+      })
+    );
+  }
+  async addFeedback(feedback) {
+    if (!this.#canEmitRecordedEvent()) {
+      this.#debugRecordedAnnotationUnavailable({ kind: "feedback", traceId: this.traceId, spanId: this.id });
+      return;
+    }
+    await this.#emitRecordedEvent(
+      buildRecordedFeedbackEvent({
+        span: this.#raw,
+        rootSpan: this.#rootSpan,
+        parent: this.parent,
+        feedback,
+        spanId: this.id
+      })
+    );
+  }
+};
+var RecordedTraceImpl = class {
+  traceId;
+  rootSpan;
+  spans;
+  #rootRecord;
+  #emitRecordedEvent;
+  #spanMap;
+  #canEmitRecordedEvent;
+  #debugRecordedAnnotationUnavailable;
+  constructor(args) {
+    this.traceId = args.traceId;
+    this.rootSpan = args.rootSpan;
+    this.#rootRecord = args.rootRecord;
+    this.spans = args.spans;
+    this.#emitRecordedEvent = args.emitRecordedEvent;
+    this.#spanMap = new Map(args.spans.map((span) => [span.id, span]));
+    this.#canEmitRecordedEvent = args.canEmitRecordedEvent;
+    this.#debugRecordedAnnotationUnavailable = args.debugRecordedAnnotationUnavailable;
+  }
+  getSpan(spanId) {
+    return this.#spanMap.get(spanId) ?? null;
+  }
+  async addScore(score) {
+    if (!this.#canEmitRecordedEvent()) {
+      this.#debugRecordedAnnotationUnavailable({ kind: "score", traceId: this.traceId });
+      return;
+    }
+    await this.#emitRecordedEvent(
+      buildRecordedScoreEvent({
+        span: this.#rootRecord,
+        rootSpan: this.#rootRecord,
+        score
+      })
+    );
+  }
+  async addFeedback(feedback) {
+    if (!this.#canEmitRecordedEvent()) {
+      this.#debugRecordedAnnotationUnavailable({ kind: "feedback", traceId: this.traceId });
+      return;
+    }
+    await this.#emitRecordedEvent(
+      buildRecordedFeedbackEvent({
+        span: this.#rootRecord,
+        rootSpan: this.#rootRecord,
+        feedback
+      })
+    );
+  }
+};
+function findRootSpan(spans) {
+  const spanIds = new Set(spans.map((span) => span.spanId));
+  return spans.find((span) => !span.parentSpanId || !spanIds.has(span.parentSpanId)) ?? spans[0];
+}
+function hydrateRecordedTrace(args) {
+  const {
+    trace,
+    emitRecordedEvent,
+    canEmitRecordedEvent = () => true,
+    debugRecordedAnnotationUnavailable = () => {
+    }
+  } = args;
+  const rootSpan = findRootSpan(trace.spans);
+  if (!rootSpan) {
+    return null;
+  }
+  const recordedSpans = trace.spans.map(
+    (raw) => new RecordedSpanImpl({
+      raw,
+      rootSpan,
+      emitRecordedEvent,
+      canEmitRecordedEvent,
+      debugRecordedAnnotationUnavailable
+    })
+  );
+  const spanMap = new Map(recordedSpans.map((span) => [span.id, span]));
+  for (const span of recordedSpans) {
+    if (!span.parentSpanId) continue;
+    const parent = spanMap.get(span.parentSpanId);
+    if (!parent) continue;
+    span.parent = parent;
+    parent.children.push(span);
+  }
+  const hydratedRootSpan = spanMap.get(rootSpan.spanId);
+  if (!hydratedRootSpan) {
+    return null;
+  }
+  return new RecordedTraceImpl({
+    traceId: trace.traceId,
+    rootSpan: hydratedRootSpan,
+    rootRecord: rootSpan,
+    spans: recordedSpans,
+    emitRecordedEvent,
+    canEmitRecordedEvent,
+    debugRecordedAnnotationUnavailable
+  });
+}
+
 // src/registry.ts
 var ObservabilityRegistry = class {
   #instances = /* @__PURE__ */ new Map();
@@ -19743,6 +20070,7 @@ function isInstance(obj) {
 }
 var Observability = class extends base.MastraBase {
   #registry = new ObservabilityRegistry();
+  #mastra;
   constructor(config2) {
     super({
       component: logger.RegisteredLogger.OBSERVABILITY,
@@ -19817,6 +20145,7 @@ var Observability = class extends base.MastraBase {
   setMastraContext(options) {
     const instances = this.listInstances();
     const { mastra } = options;
+    this.#mastra = mastra;
     instances.forEach((instance) => {
       const config2 = instance.getConfig();
       const exporters = instance.getExporters();
@@ -19845,6 +20174,60 @@ var Observability = class extends base.MastraBase {
   getSelectedInstance(options) {
     return this.#registry.getSelected(options);
   }
+  async getRecordedTrace(args) {
+    const observabilityStorage = await this.#getObservabilityStorage();
+    if (!observabilityStorage) {
+      return null;
+    }
+    const trace = await observabilityStorage.getTrace({ traceId: args.traceId });
+    if (!trace) {
+      return null;
+    }
+    return hydrateRecordedTrace({
+      trace,
+      emitRecordedEvent: (event) => this.#emitRecordedEvent(event),
+      canEmitRecordedEvent: () => !!this.#getRecordedTraceInstance(),
+      debugRecordedAnnotationUnavailable: ({ kind, traceId, spanId }) => {
+        this.logger?.debug(
+          kind === "score" ? "addScore() is unavailable; rehydrate the trace before calling addScore()" : "addFeedback() is unavailable; rehydrate the trace before calling addFeedback()",
+          {
+            traceId,
+            spanId
+          }
+        );
+      }
+    });
+  }
+  async addScore(args) {
+    const trace = await this.#getStoredTrace(args.traceId);
+    if (!trace) {
+      return;
+    }
+    const event = buildRecordedScoreEventFromTrace({
+      trace,
+      spanId: args.spanId,
+      score: args.score
+    });
+    if (!event) {
+      return;
+    }
+    await this.#emitRecordedEvent(event);
+  }
+  async addFeedback(args) {
+    const trace = await this.#getStoredTrace(args.traceId);
+    if (!trace) {
+      return;
+    }
+    const event = buildRecordedFeedbackEventFromTrace({
+      trace,
+      spanId: args.spanId,
+      feedback: args.feedback
+    });
+    if (!event) {
+      return;
+    }
+    await this.#emitRecordedEvent(event);
+  }
   /** Register a named observability instance, optionally marking it as default. */
   registerInstance(name, instance, isDefault = false) {
     this.#registry.register(name, instance, isDefault);
@@ -19881,6 +20264,45 @@ var Observability = class extends base.MastraBase {
   async shutdown() {
     await this.#registry.shutdown();
   }
+  async #getObservabilityStorage() {
+    const storage = this.#mastra?.getStorage();
+    if (!storage) {
+      return null;
+    }
+    return await storage.getStore("observability") ?? null;
+  }
+  async #getStoredTrace(traceId) {
+    const observabilityStorage = await this.#getObservabilityStorage();
+    if (!observabilityStorage) {
+      return null;
+    }
+    return observabilityStorage.getTrace({ traceId });
+  }
+  #getRecordedTraceInstance() {
+    return this.getDefaultInstance() ?? Array.from(this.listInstances().values())[0];
+  }
+  async #emitRecordedEvent(event) {
+    const instance = this.#getRecordedTraceInstance();
+    if (!instance) {
+      this.logger?.debug(
+        event.type === "score" ? "Score event was dropped because no observability instance is registered" : "Feedback event was dropped because no observability instance is registered",
+        { eventType: event.type }
+      );
+      return;
+    }
+    if (instance instanceof BaseObservabilityInstance) {
+      instance.__emitRecordedEvent(event);
+      return;
+    }
+    const bridge = instance.getBridge();
+    const handlerResults = [
+      ...instance.getExporters().map((exporter) => routeToHandler(exporter, event, this.logger)),
+      ...bridge ? [routeToHandler(bridge, event, this.logger)] : []
+    ].filter((result) => !!result && typeof result.then === "function");
+    if (handlerResults.length > 0) {
+      await Promise.allSettled(handlerResults);
+    }
+  }
 };
 
 // src/tracing-options.ts