@mastra/otel-bridge 1.4.3 → 1.4.4

package/dist/index.js

@@ -1,271 +1,268 @@
-import { TracingEventType } from '@mastra/core/observability';
-import { BaseExporter, getExternalParentId } from '@mastra/observability';
-import { convertLog, SpanConverter, getSpanKind } from '@mastra/otel-exporter';
-import { trace, isSpanContextValid, TraceFlags, context } from '@opentelemetry/api';
-import { logs } from '@opentelemetry/api-logs';
-
-// src/bridge.ts
+import { TracingEventType } from "@mastra/core/observability";
+import { BaseExporter, getExternalParentId } from "@mastra/observability";
+import { SpanConverter, convertLog, getSpanKind } from "@mastra/otel-exporter";
+import { TraceFlags, context, isSpanContextValid, trace } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+//#region src/bridge.ts
+/**
+* OpenTelemetry Bridge implementation
+*
+* Creates real OTEL spans when Mastra spans are created, maintaining proper
+* context propagation for nested instrumentation.
+*
+* @example
+* ```typescript
+* import { OtelBridge } from '@mastra/otel-bridge';
+* import { Mastra } from '@mastra/core';
+*
+* const mastra = new Mastra({
+*   agents: { myAgent },
+*   observability: {
+*     configs: {
+*       default: {
+*         serviceName: 'my-service',
+*         bridge: new OtelBridge(),
+*       }
+*     }
+*   }
+* });
+* ```
+*/
 var OtelBridge = class extends BaseExporter {
-  name = "otel";
-  tracerProvider;
-  loggerProvider;
-  otelTracer;
-  otelLogger;
-  otelSpanMap = /* @__PURE__ */ new Map();
-  spanConverter;
-  constructor(config = {}) {
-    super(config);
-    this.tracerProvider = config.tracerProvider ?? trace.getTracerProvider();
-    this.otelTracer = this.tracerProvider.getTracer("@mastra/otel-bridge", "1.0.0");
-    this.loggerProvider = config.loggerProvider ?? logs.getLoggerProvider();
-    this.otelLogger = this.loggerProvider.getLogger("@mastra/otel-bridge", "1.0.0");
-  }
-  /**
-   * Handle Mastra tracing events
-   *
-   * Ships OTEL spans when Mastra spans end.
-   * This maintains proper span hierarchy and allows OTEL-instrumented code within
-   * Mastra spans to have correct parent-child relationships.
-   * Note: OTEL spans are created when registerSpan is called when the span is first created.
-   */
-  async _exportTracingEvent(event) {
-    if (event.type === TracingEventType.SPAN_ENDED) {
-      await this.handleSpanEnded(event);
-    }
-  }
-  /**
-   * Forward Mastra log events into the globally-registered OTEL LoggerProvider.
-   *
-   * If the user has not registered a LoggerProvider (e.g. via @opentelemetry/sdk-logs
-   * or NodeSDK's logRecordProcessor option), the API returns a no-op logger and
-   * emit() is a silent no-op — the bridge degrades gracefully.
-   *
-   * Trace correlation:
-   * - If the log carries a spanId we have an OTEL span for, emit under that span's
-   *   stored context so the log nests beneath it in the trace.
-   * - Else if the log carries traceId+spanId, attach a SpanContext built from those
-   *   IDs so backends still correlate by ID.
-   * - Else emit under whatever context is currently active.
-   */
-  async onLogEvent(event) {
-    if (this.isDisabled) return;
-    try {
-      const params = convertLog(event.log);
-      const attributes = { ...params.attributes };
-      if (params.traceId) attributes["mastra.traceId"] = params.traceId;
-      if (params.spanId) attributes["mastra.spanId"] = params.spanId;
-      const logContext = this.resolveLogContext(params.traceId, params.spanId);
-      this.otelLogger.emit({
-        timestamp: params.timestamp,
-        severityNumber: params.severityNumber,
-        severityText: params.severityText,
-        body: params.body,
-        attributes,
-        context: logContext
-      });
-    } catch (error) {
-      this.logger.error("[OtelBridge] Failed to emit log:", error);
-    }
-  }
-  /**
-   * Pick the OTEL Context to emit a log under so trace correlation is correct.
-   */
-  resolveLogContext(traceId, spanId) {
-    if (spanId) {
-      const entry = this.otelSpanMap.get(spanId);
-      if (entry) return entry.otelContext;
-    }
-    if (traceId && spanId) {
-      const candidate = {
-        traceId,
-        spanId,
-        traceFlags: TraceFlags.SAMPLED,
-        isRemote: false
-      };
-      if (isSpanContextValid(candidate)) {
-        return trace.setSpanContext(context.active(), candidate);
-      }
-    }
-    return context.active();
-  }
-  /**
-   * Initialize with tracing configuration
-   */
-  init(options) {
-    this.spanConverter = new SpanConverter({
-      packageName: "@mastra/otel-bridge",
-      serviceName: options.config?.serviceName,
-      format: "GenAI_v1_38_0"
-    });
-  }
-  /**
-   * Create a span in the bridge's tracing system.
-   * Called during Mastra span construction to get bridge-generated identifiers.
-   *
-   * @param options - Span creation options from Mastra
-   * @returns Span identifiers (spanId, traceId, parentSpanId) from bridge, or undefined if creation fails
-   */
-  createSpan(options) {
-    try {
-      let parentOtelContext = context.active();
-      const externalParentId = getExternalParentId(options);
-      if (externalParentId) {
-        const parentEntry = this.otelSpanMap.get(externalParentId);
-        if (parentEntry) {
-          parentOtelContext = parentEntry.otelContext;
-        }
-      }
-      const otelSpan = this.otelTracer.startSpan(
-        options.name,
-        {
-          kind: getSpanKind(options.type)
-        },
-        parentOtelContext
-      );
-      const spanContext = trace.setSpan(parentOtelContext, otelSpan);
-      const otelSpanContext = otelSpan.spanContext();
-      if (!isSpanContextValid(otelSpanContext)) {
-        otelSpan.end();
-        return void 0;
-      }
-      const spanId = otelSpanContext.spanId;
-      const traceId = otelSpanContext.traceId;
-      this.otelSpanMap.set(spanId, { otelSpan, otelContext: spanContext });
-      const parentSpan = trace.getSpan(parentOtelContext);
-      const parentSpanContext = parentSpan?.spanContext();
-      const parentSpanId = parentSpanContext && isSpanContextValid(parentSpanContext) ? parentSpanContext.spanId : void 0;
-      this.logger.debug(
-        `[OtelBridge.createSpan] Created span [spanId=${spanId}] [traceId=${traceId}] [parentSpanId=${parentSpanId}] [type=${options.type}] [mapSize=${this.otelSpanMap.size}]`
-      );
-      return { spanId, traceId, parentSpanId };
-    } catch (error) {
-      this.logger.error("[OtelBridge] Failed to create span:", error);
-      return void 0;
-    }
-  }
-  /**
-   * Handle SPAN_ENDED event
-   *
-   * Retrieves the OTEL span created at SPAN_STARTED, sets all final attributes,
-   * events, and status, then ends the span. Cleans up the span map entry.
-   */
-  async handleSpanEnded(event) {
-    try {
-      const mastraSpan = event.exportedSpan;
-      const entry = this.otelSpanMap.get(mastraSpan.id);
-      if (!entry) {
-        this.logger.warn(`[OtelBridge] No OTEL span found for Mastra span [id=${mastraSpan.id}].`);
-        return;
-      }
-      this.otelSpanMap.delete(mastraSpan.id);
-      if (!this.spanConverter) {
-        return;
-      }
-      const { otelSpan } = entry;
-      this.logger.debug(`[OtelBridge] Ending OTEL span [mastraId=${mastraSpan.id}] [name=${mastraSpan.name}]`);
-      const readableSpan = await this.spanConverter.convertSpan(mastraSpan);
-      otelSpan.updateName(readableSpan.name);
-      for (const [key, value] of Object.entries(readableSpan.attributes)) {
-        if (value !== void 0 && value !== null && typeof value !== "object") {
-          otelSpan.setAttribute(key, value);
-        }
-      }
-      otelSpan.setStatus(readableSpan.status);
-      for (const event2 of readableSpan.events) {
-        if (event2.name === "exception" && event2.attributes) {
-          const error = new Error(event2.attributes["exception.message"]);
-          otelSpan.recordException(error);
-        }
-      }
-      otelSpan.end(mastraSpan.endTime);
-      this.logger.debug(
-        `[OtelBridge] Completed OTEL span [mastraId=${mastraSpan.id}] [traceId=${otelSpan.spanContext().traceId}]`
-      );
-    } catch (error) {
-      this.logger.error("[OtelBridge] Failed to handle SPAN_ENDED:", error);
-    }
-  }
-  /**
-   * Execute a function (sync or async) within the OTEL context of a Mastra span.
-   * Retrieves the stored OTEL context for the span and executes the function within it.
-   *
-   * This is the core implementation used by both executeInContext and executeInContextSync.
-   *
-   * @param spanId - The ID of the Mastra span to use as context
-   * @param fn - The function to execute within the span context
-   * @returns The result of the function execution
-   */
-  executeWithSpanContext(spanId, fn) {
-    const entry = this.otelSpanMap.get(spanId);
-    this.logger.debug(
-      `[OtelBridge.executeWithSpanContext] spanId=${spanId}, inMap=${!!entry}, storedOtelSpan=${entry?.otelSpan.spanContext().spanId || "none"}`
-    );
-    const spanContext = entry?.otelContext;
-    if (spanContext) {
-      return context.with(spanContext, fn);
-    }
-    return fn();
-  }
-  /**
-   * Execute an async function within the OTEL context of a Mastra span.
-   *
-   * @param spanId - The ID of the Mastra span to use as context
-   * @param fn - The async function to execute within the span context
-   * @returns The result of the function execution
-   */
-  executeInContext(spanId, fn) {
-    return this.executeWithSpanContext(spanId, fn);
-  }
-  /**
-   * Execute a synchronous function within the OTEL context of a Mastra span.
-   *
-   * @param spanId - The ID of the Mastra span to use as context
-   * @param fn - The synchronous function to execute within the span context
-   * @returns The result of the function execution
-   */
-  executeInContextSync(spanId, fn) {
-    return this.executeWithSpanContext(spanId, fn);
-  }
-  /**
-   * Force flush any buffered spans without shutting down the bridge.
-   *
-   * Attempts to flush the underlying OTEL tracer provider if it supports
-   * the forceFlush operation. This is useful in serverless environments
-   * where you need to ensure all spans are exported before the runtime
-   * instance is terminated.
-   */
-  async flush() {
-    await this.flushProvider(this.tracerProvider, "tracer");
-    await this.flushProvider(this.loggerProvider, "logger");
-  }
-  async flushProvider(provider, label) {
-    try {
-      if (provider && typeof provider === "object" && "forceFlush" in provider && typeof provider.forceFlush === "function") {
-        await provider.forceFlush();
-        this.logger.debug(`[OtelBridge] Flushed ${label} provider`);
-      } else {
-        this.logger.debug(
-          `[OtelBridge] ${label === "tracer" ? "Tracer" : "Logger"} provider does not support forceFlush`
-        );
-      }
-    } catch (error) {
-      this.logger.error(`[OtelBridge] Failed to flush ${label} provider:`, error);
-    }
-  }
-  /**
-   * Shutdown the bridge and clean up resources
-   */
-  async shutdown() {
-    await this.flush();
-    for (const [spanId, { otelSpan }] of this.otelSpanMap.entries()) {
-      this.logger.warn(`[OtelBridge] Force-ending span that was not properly closed [id=${spanId}]`);
-      otelSpan.end();
-    }
-    this.otelSpanMap.clear();
-    this.logger.info("[OtelBridge] Shutdown complete");
-  }
+	name = "otel";
+	tracerProvider;
+	loggerProvider;
+	otelTracer;
+	otelLogger;
+	otelSpanMap = /* @__PURE__ */ new Map();
+	spanConverter;
+	constructor(config = {}) {
+		super(config);
+		this.tracerProvider = config.tracerProvider ?? trace.getTracerProvider();
+		this.otelTracer = this.tracerProvider.getTracer("@mastra/otel-bridge", "1.0.0");
+		this.loggerProvider = config.loggerProvider ?? logs.getLoggerProvider();
+		this.otelLogger = this.loggerProvider.getLogger("@mastra/otel-bridge", "1.0.0");
+	}
+	/**
+	* Handle Mastra tracing events
+	*
+	* Ships OTEL spans when Mastra spans end.
+	* This maintains proper span hierarchy and allows OTEL-instrumented code within
+	* Mastra spans to have correct parent-child relationships.
+	* Note: OTEL spans are created when registerSpan is called when the span is first created.
+	*/
+	async _exportTracingEvent(event) {
+		if (event.type === TracingEventType.SPAN_ENDED) await this.handleSpanEnded(event);
+	}
+	/**
+	* Forward Mastra log events into the globally-registered OTEL LoggerProvider.
+	*
+	* If the user has not registered a LoggerProvider (e.g. via @opentelemetry/sdk-logs
+	* or NodeSDK's logRecordProcessor option), the API returns a no-op logger and
+	* emit() is a silent no-op — the bridge degrades gracefully.
+	*
+	* Trace correlation:
+	* - If the log carries a spanId we have an OTEL span for, emit under that span's
+	*   stored context so the log nests beneath it in the trace.
+	* - Else if the log carries traceId+spanId, attach a SpanContext built from those
+	*   IDs so backends still correlate by ID.
+	* - Else emit under whatever context is currently active.
+	*/
+	async onLogEvent(event) {
+		if (this.isDisabled) return;
+		try {
+			const params = convertLog(event.log);
+			const attributes = { ...params.attributes };
+			if (params.traceId) attributes["mastra.traceId"] = params.traceId;
+			if (params.spanId) attributes["mastra.spanId"] = params.spanId;
+			const logContext = this.resolveLogContext(params.traceId, params.spanId);
+			this.otelLogger.emit({
+				timestamp: params.timestamp,
+				severityNumber: params.severityNumber,
+				severityText: params.severityText,
+				body: params.body,
+				attributes,
+				context: logContext
+			});
+		} catch (error) {
+			this.logger.error("[OtelBridge] Failed to emit log:", error);
+		}
+	}
+	/**
+	* Pick the OTEL Context to emit a log under so trace correlation is correct.
+	*/
+	resolveLogContext(traceId, spanId) {
+		if (spanId) {
+			const entry = this.otelSpanMap.get(spanId);
+			if (entry) return entry.otelContext;
+		}
+		if (traceId && spanId) {
+			const candidate = {
+				traceId,
+				spanId,
+				traceFlags: TraceFlags.SAMPLED,
+				isRemote: false
+			};
+			if (isSpanContextValid(candidate)) return trace.setSpanContext(context.active(), candidate);
+		}
+		return context.active();
+	}
+	/**
+	* Initialize with tracing configuration
+	*/
+	init(options) {
+		this.spanConverter = new SpanConverter({
+			packageName: "@mastra/otel-bridge",
+			serviceName: options.config?.serviceName,
+			format: "GenAI_v1_38_0"
+		});
+	}
+	/**
+	* Create a span in the bridge's tracing system.
+	* Called during Mastra span construction to get bridge-generated identifiers.
+	*
+	* @param options - Span creation options from Mastra
+	* @returns Span identifiers (spanId, traceId, parentSpanId) from bridge, or undefined if creation fails
+	*/
+	createSpan(options) {
+		try {
+			let parentOtelContext = context.active();
+			const externalParentId = getExternalParentId(options);
+			if (externalParentId) {
+				const parentEntry = this.otelSpanMap.get(externalParentId);
+				if (parentEntry) parentOtelContext = parentEntry.otelContext;
+			}
+			const otelSpan = this.otelTracer.startSpan(options.name, { kind: getSpanKind(options.type) }, parentOtelContext);
+			const spanContext = trace.setSpan(parentOtelContext, otelSpan);
+			const otelSpanContext = otelSpan.spanContext();
+			if (!isSpanContextValid(otelSpanContext)) {
+				otelSpan.end();
+				return;
+			}
+			const spanId = otelSpanContext.spanId;
+			const traceId = otelSpanContext.traceId;
+			this.otelSpanMap.set(spanId, {
+				otelSpan,
+				otelContext: spanContext
+			});
+			const parentSpanContext = trace.getSpan(parentOtelContext)?.spanContext();
+			const parentSpanId = parentSpanContext && isSpanContextValid(parentSpanContext) ? parentSpanContext.spanId : void 0;
+			this.logger.debug(`[OtelBridge.createSpan] Created span [spanId=${spanId}] [traceId=${traceId}] [parentSpanId=${parentSpanId}] [type=${options.type}] [mapSize=${this.otelSpanMap.size}]`);
+			return {
+				spanId,
+				traceId,
+				parentSpanId
+			};
+		} catch (error) {
+			this.logger.error("[OtelBridge] Failed to create span:", error);
+			return;
+		}
+	}
+	/**
+	* Handle SPAN_ENDED event
+	*
+	* Retrieves the OTEL span created at SPAN_STARTED, sets all final attributes,
+	* events, and status, then ends the span. Cleans up the span map entry.
+	*/
+	async handleSpanEnded(event) {
+		try {
+			const mastraSpan = event.exportedSpan;
+			const entry = this.otelSpanMap.get(mastraSpan.id);
+			if (!entry) {
+				this.logger.warn(`[OtelBridge] No OTEL span found for Mastra span [id=${mastraSpan.id}].`);
+				return;
+			}
+			this.otelSpanMap.delete(mastraSpan.id);
+			if (!this.spanConverter) return;
+			const { otelSpan } = entry;
+			this.logger.debug(`[OtelBridge] Ending OTEL span [mastraId=${mastraSpan.id}] [name=${mastraSpan.name}]`);
+			const readableSpan = await this.spanConverter.convertSpan(mastraSpan);
+			otelSpan.updateName(readableSpan.name);
+			for (const [key, value] of Object.entries(readableSpan.attributes)) if (value !== void 0 && value !== null && typeof value !== "object") otelSpan.setAttribute(key, value);
+			otelSpan.setStatus(readableSpan.status);
+			for (const event of readableSpan.events) if (event.name === "exception" && event.attributes) {
+				const error = new Error(event.attributes["exception.message"]);
+				otelSpan.recordException(error);
+			}
+			otelSpan.end(mastraSpan.endTime);
+			this.logger.debug(`[OtelBridge] Completed OTEL span [mastraId=${mastraSpan.id}] [traceId=${otelSpan.spanContext().traceId}]`);
+		} catch (error) {
+			this.logger.error("[OtelBridge] Failed to handle SPAN_ENDED:", error);
+		}
+	}
+	/**
+	* Execute a function (sync or async) within the OTEL context of a Mastra span.
+	* Retrieves the stored OTEL context for the span and executes the function within it.
+	*
+	* This is the core implementation used by both executeInContext and executeInContextSync.
+	*
+	* @param spanId - The ID of the Mastra span to use as context
+	* @param fn - The function to execute within the span context
+	* @returns The result of the function execution
+	*/
+	executeWithSpanContext(spanId, fn) {
+		const entry = this.otelSpanMap.get(spanId);
+		this.logger.debug(`[OtelBridge.executeWithSpanContext] spanId=${spanId}, inMap=${!!entry}, storedOtelSpan=${entry?.otelSpan.spanContext().spanId || "none"}`);
+		const spanContext = entry?.otelContext;
+		if (spanContext) return context.with(spanContext, fn);
+		return fn();
+	}
+	/**
+	* Execute an async function within the OTEL context of a Mastra span.
+	*
+	* @param spanId - The ID of the Mastra span to use as context
+	* @param fn - The async function to execute within the span context
+	* @returns The result of the function execution
+	*/
+	executeInContext(spanId, fn) {
+		return this.executeWithSpanContext(spanId, fn);
+	}
+	/**
+	* Execute a synchronous function within the OTEL context of a Mastra span.
+	*
+	* @param spanId - The ID of the Mastra span to use as context
+	* @param fn - The synchronous function to execute within the span context
+	* @returns The result of the function execution
+	*/
+	executeInContextSync(spanId, fn) {
+		return this.executeWithSpanContext(spanId, fn);
+	}
+	/**
+	* Force flush any buffered spans without shutting down the bridge.
+	*
+	* Attempts to flush the underlying OTEL tracer provider if it supports
+	* the forceFlush operation. This is useful in serverless environments
+	* where you need to ensure all spans are exported before the runtime
+	* instance is terminated.
+	*/
+	async flush() {
+		await this.flushProvider(this.tracerProvider, "tracer");
+		await this.flushProvider(this.loggerProvider, "logger");
+	}
+	async flushProvider(provider, label) {
+		try {
+			if (provider && typeof provider === "object" && "forceFlush" in provider && typeof provider.forceFlush === "function") {
+				await provider.forceFlush();
+				this.logger.debug(`[OtelBridge] Flushed ${label} provider`);
+			} else this.logger.debug(`[OtelBridge] ${label === "tracer" ? "Tracer" : "Logger"} provider does not support forceFlush`);
+		} catch (error) {
+			this.logger.error(`[OtelBridge] Failed to flush ${label} provider:`, error);
+		}
+	}
+	/**
+	* Shutdown the bridge and clean up resources
+	*/
+	async shutdown() {
+		await this.flush();
+		for (const [spanId, { otelSpan }] of this.otelSpanMap.entries()) {
+			this.logger.warn(`[OtelBridge] Force-ending span that was not properly closed [id=${spanId}]`);
+			otelSpan.end();
+		}
+		this.otelSpanMap.clear();
+		this.logger.info("[OtelBridge] Shutdown complete");
+	}
 };
-
+//#endregion
 export { OtelBridge };
-//# sourceMappingURL=index.js.map
+
 //# sourceMappingURL=index.js.map