Skip to main content

OtelBridge

warning

The OpenTelemetry Bridge is currently experimental. APIs and configuration options may change in future releases.

Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.

Constructor
Direct link to Constructor

new OtelBridge()

Methods
Direct link to Methods

executeInContext
Direct link to executeInContext

executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>

Executes an async function within the OTEL context of a Mastra span. OTEL-instrumented code running inside the function will have correct parent relationships.

Returns: Promise<T> - The result of the function execution.

executeInContextSync
Direct link to executeInContextSync

executeInContextSync<T>(spanId: string, fn: () => T): T

Executes a synchronous function within the OTEL context of a Mastra span.

Returns: T - The result of the function execution.

shutdown
Direct link to shutdown

async shutdown(): Promise<void>

Shuts down the bridge and cleans up resources. Ends any spans that were not properly closed.

Usage Examples
Direct link to Usage Examples

Basic Usage
Direct link to Basic Usage

import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { OtelBridge } from "@mastra/otel-bridge";

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: "my-service",
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: { myAgent },
});

Combined with Exporters
Direct link to Combined with Exporters

The bridge can be used alongside exporters. The bridge handles OTEL context, while exporters send data to additional destinations:

import { Mastra } from "@mastra/core";
import { Observability, DefaultExporter } from "@mastra/observability";
import { OtelBridge } from "@mastra/otel-bridge";
import { LangfuseExporter } from "@mastra/langfuse";

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: "my-service",
        bridge: new OtelBridge(), // Handles OTEL context
        exporters: [
          new DefaultExporter(), // Studio access
          new LangfuseExporter({
            // Additional destination
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
          }),
        ],
      },
    },
  }),
});

OpenTelemetry Setup Requirements
Direct link to OpenTelemetry Setup Requirements

The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.

See the OtelBridge Guide for complete setup instructions, including how to configure OTEL instrumentation and run your application.

Tags Support
Direct link to Tags Support

The OtelBridge supports trace tagging for categorization and filtering. Tags are only applied to root spans and are included as the mastra.tags attribute on native OTEL spans.

Usage
Direct link to Usage

const result = await agent.generate({
  messages: [{ role: "user", content: "Hello" }],
  tracingOptions: {
    tags: ["production", "experiment-v2", "user-request"],
  },
});

How Tags Are Stored
Direct link to How Tags Are Stored

Tags are stored as a JSON-stringified array in the mastra.tags span attribute:

{
  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
}

This format ensures compatibility with all OTEL-compatible backends and collectors.