OpenTelemetry bridge

경고

The OpenTelemetry Bridge is currently experimental. 향후 릴리스에서 APIs 및 구성 옵션이 변경될 수 있습니다.

OpenTelemetry(OTEL) Bridge는 Mastra의 추적 시스템과 기존 OpenTelemetry 인프라 간 양방향 통합을 지원합니다. Trace 데이터를 외부 플랫폼으로 전송하는 exporter와 달리, Bridge는 분산 추적 컨텍스트에 참여하는 네이티브 OTEL span을 생성합니다.

기존 OTEL 인프라 없이 Trace를 전송하려고 하나요?

기존 OpenTelemetry 계측이 없다면, OpenTelemetry Exporter 가 더 간단할 수 있습니다. OTEL SDK를 설정하지 않아도 Trace를 직접 전송합니다.

When to use the bridge

Use the OtelBridge when you:

• 애플리케이션에 기존 OTEL 계측(HTTP 서버, 데이터베이스 클라이언트 등)이 있는 경우
• Mastra 작업을 기존 OTEL Trace의 자식 span으로 표시하려는 경우
• Mastra Tool 내부의 OTEL 계측 코드에서 올바른 부모-자식 관계를 유지해야 하는 경우
• Trace 컨텍스트가 서비스 간에 전파되어야 하는 분산 시스템을 구축하는 경우

How it works

The OtelBridge provides two-way integration:

From OTEL to Mastra:

• Reads from OTEL ambient context (AsyncLocalStorage) automatically
• 활성 OTEL span에서 Trace ID와 부모 span ID를 상속합니다
• OTEL 샘플링 결정을 따릅니다. Trace가 샘플링되지 않으면 Mastra는 해당 Trace의 span을 생성하지 않습니다
• OTEL 자동 계측이 활성화되어 있으면 Trace ID를 수동으로 전달할 필요가 없습니다

From Mastra to OTEL:

• Mastra 작업(Agent, LLM 호출, Tool, Workflow)에 대한 네이티브 OTEL span을 생성합니다
• Maintains proper parent-child relationships in distributed traces
• Mastra 작업 내에서 OTEL로 계측된 코드(HTTP 클라이언트, 데이터베이스 호출)가 올바르게 중첩되도록 합니다
• Mastra 로그 이벤트를 전역으로 등록된 OTEL LoggerProvider로 전달합니다. Mastra span 내부에서 발생한 로그는 해당 span의 OTEL 컨텍스트에서 내보내지므로 백엔드에서 이를 Trace와 연관 지을 수 있습니다. LoggerProvider 가 등록되어 있지 않으면 로그를 내보내는 작업은 아무 동작 없이 조용히 종료됩니다.

Installation

npm

npm install @mastra/otel-bridge

pnpm

pnpm add @mastra/otel-bridge

Yarn

yarn add @mastra/otel-bridge

Bun

bun add @mastra/otel-bridge

Bridge는 기존 OpenTelemetry 설정과 함께 작동합니다. 구성에 따라 다음 패키지 중 일부가 추가로 필요할 수 있습니다:

• @opentelemetry/sdk-node - Core Node.js SDK for OTEL
• @opentelemetry/auto-instrumentations-node - Auto-instrumentation for common libraries
• @opentelemetry/exporter-trace-otlp-proto - OTLP exporter (Protobuf over HTTP)
• @opentelemetry/exporter-trace-otlp-http - OTLP exporter (JSON over HTTP)
• @opentelemetry/exporter-trace-otlp-grpc - OTLP exporter (gRPC)
• @opentelemetry/sdk-trace-base - Base tracing SDK (for BatchSpanProcessor, etc.)
• @opentelemetry/core - Core utilities (for W3CTraceContextPropagator, etc.)
• @opentelemetry/sdk-logs and an OTLP log exporter (e.g. @opentelemetry/exporter-logs-otlp-http) - Bridge에서 Mastra 로그 이벤트도 전달하도록 하려면 필요합니다

Configuration

Using the OtelBridge requires two steps:

1. Configure OpenTelemetry instrumentation in your application
2. Mastra Observability 구성에 OtelBridge 추가

Step 1: OpenTelemetry Instrumentation

OTEL을 초기화하는 계측 파일을 생성합니다. 이 파일은 애플리케이션 코드보다 먼저 실행되어야 합니다:

instrumentation.ts

import { NodeSDK } from '@opentelemetry/sdk-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { W3CTraceContextPropagator } from '@opentelemetry/core'

const sdk = new NodeSDK({
  serviceName: 'my-service',
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
      }),
    ),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
  textMapPropagator: new W3CTraceContextPropagator(),
})

sdk.start()

export { sdk }

Step 2: Mastra Configuration

Mastra Observability 구성에 OtelBridge를 추가합니다:

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: {/* your agents */},
})

Bridge를 사용할 때는 Mastra exporter가 필요하지 않습니다. Trace는 OTEL SDK 구성을 통해 전송됩니다. Trace를 추가 대상으로도 전송하려면 Mastra exporter를 선택적으로 추가할 수 있습니다.

Forwarding logs (optional)

Bridge는 Mastra 로그 이벤트도 전역으로 등록된 OTEL LoggerProvider로 전달합니다. Trace와 함께 로그도 연결하려면 logRecordProcessor on NodeSDK:

instrumentation.ts

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'

const sdk = new NodeSDK({
  // ...trace config as usual
  logRecordProcessor: new BatchLogRecordProcessor(
    new OTLPLogExporter({
      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
    }),
  ),
})

Mastra span 내부에서 발생한 로그는 해당 span의 OTEL 컨텍스트에서 내보내지므로 Datadog, Grafana, Honeycomb 같은 백엔드가 이를 주변 Trace와 자동으로 연관 짓습니다. Trace 컨텍스트가 없는 로그에는 현재 활성화된 OTEL 컨텍스트가 사용됩니다.

If you don't register a LoggerProvider가 없으면 로그를 내보내는 작업은 아무 동작 없이 조용히 종료되며, Trace는 구성된 대로 계속 작동합니다.

Running Your Application

Use the --import 플래그를 사용하여 애플리케이션보다 먼저 계측이 로드되도록 합니다:

tsx --import ./instrumentation.ts ./src/index.ts

Semantic conventions

The OtelBridge exports Mastra spans using OpenTelemetry Semantic Conventions for GenAI v1.38.0. This includes standardized span names (chat {model}, execute_tool {tool_name}, etc.) and attributes (gen_ai.usage.input_tokens, gen_ai.request.model, etc.).

span 명명 및 속성에 대한 자세한 내용은 OpenTelemetry Exporter semantic conventions.

Trace hierarchy

OtelBridge를 사용하면 OTEL과 Mastra 경계를 넘어서도 Trace의 올바른 계층 구조가 유지됩니다:

HTTP POST /api/chat (from Hono middleware)
└── agent.assistant (from Mastra via OtelBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
    └── chat gpt-5.4 (follow-up LLM call)

Multi-service distributed tracing

OtelBridge는 서비스 경계를 넘는 Trace 전파를 지원합니다. Service A가 HTTP를 통해 Service B를 호출하면 Trace 컨텍스트가 자동으로 전파됩니다:

Service A: HTTP POST /api/process
└── HTTP POST service-b/api/analyze (outgoing call)

Service B: HTTP POST /api/analyze (incoming call - same trace!)
└── agent.analyzer (Mastra agent inherits trace context)
    └── chat gpt-5.4

Both services must have:

1. OTEL instrumentation configured
2. W3C Trace Context propagator enabled
3. Mastra with OtelBridge configured

Using tags

태그를 사용하면 OTEL 백엔드에서 Trace를 분류하고 필터링할 수 있습니다. Agent 또는 Workflow를 실행할 때 태그를 추가하세요:

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

Tags are exported as a JSON string in the mastra.tags span 속성을 사용하여 다양한 백엔드와의 호환성을 확보합니다. 일반적인 사용 사례는 다음과 같습니다:

• Environment labels: "production", "staging"
• Experiment tracking: "experiment-v1", "control-group"
• Priority levels: "priority-high", "batch-job"

Troubleshooting

Trace가 예상대로 표시되거나 연결되지 않는 경우:

• OTEL SDK가 Mastra보다 먼저 초기화되었는지 확인합니다( --import flag or import at top of entry point)
• Observability 구성에 OtelBridge가 추가되었는지 확인합니다
• OTEL 백엔드가 실행 중이며 접근 가능한지 확인합니다

Related

• Tracing Overview
• OpenTelemetry Exporter: For sending traces to OTEL backends
• OtelBridge Reference: API documentation