@mastra/core/dist/docs/references/reference-observability-tracing-bridges-otel.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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. Also forwards Mastra log events to the globally-registered OTEL `LoggerProvider`, emitting each log under the OTEL context of the originating Mastra span so trace-log correlation works automatically.

## Constructor

```typescript
new OtelBridge()
```

## Methods

### `executeInContext`

```typescript
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`

```typescript
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.

### `onLogEvent`

```typescript
async onLogEvent(event: LogEvent): Promise<void>
```

Forwards a Mastra log event to the globally-registered OTEL `LoggerProvider`. Trace correlation is resolved in this order:

1. If the log carries a `spanId` the bridge has an OTEL span for, the log is emitted under that span's stored OTEL context.
2. Otherwise, if the log carries `traceId` and `spanId`, those IDs are attached to the emitted log record's `SpanContext`.
3. Otherwise, the log is emitted under whatever OTEL context is currently active.

If no `LoggerProvider` is registered globally, emission is a silent no-op.

### `flush`

```typescript
async flush(): Promise<void>
```

Force flushes the global OTEL tracer provider and logger provider if they support `forceFlush`. Useful in serverless environments where you need to drain telemetry before the runtime terminates.

### `shutdown`

```typescript
async shutdown(): Promise<void>
```

Shuts down the bridge and cleans up resources. Ends any spans that weren't properly closed.

## Usage examples

### Basic Usage

```typescript
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

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

```typescript
import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } 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 MastraStorageExporter(), // Studio access
          new LangfuseExporter({
            // Additional destination
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
          }),
        ],
      },
    },
  }),
})
```

## `OpenTelemetry` setup requirements

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

See the [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.

## 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

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})
```

### How Tags Are Stored

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

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

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

## Related

- [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel): Setup guide with examples
- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts
- [OtelExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel): OTEL exporter for sending traces