오텔브릿지

경고

OpenTelemetry Bridge는 현재experimental. API와 구성 옵션은 향후 릴리스에서 변경될 수 있습니다.

Mastra 추적과 OpenTelemetry 인프라 간의 양방향 통합을 지원합니다. Mastra 작업을 위한 기본 OTEL 범위를 생성하고 활성 OTEL 범위에서 컨텍스트를 상속합니다. 또한 Mastra 로그 이벤트를 전 세계적으로 등록된 OTEL로 전달합니다.LoggerProvider, 각 로그를 해당 로그가 생성된 Mastra Span의 OTEL 컨텍스트에서 내보내므로 Trace와 로그의 상관관계가 자동으로 작동합니다.

건설자

new OtelBridge()

행동 양식

executeInContext

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

Mastra 범위의 OTEL 컨텍스트 내에서 비동기 기능을 실행합니다. 함수 내부에서 실행되는 OTEL 계측 코드는 올바른 상위 관계를 갖게 됩니다.

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

executeInContextSync

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

Mastra 범위의 OTEL 컨텍스트 내에서 동기 기능을 실행합니다.

보고: T - The result of the function execution.

onLogEvent

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

전 세계적으로 등록된 OTEL로 Mastra 로그 이벤트를 전달합니다.LoggerProvider. Trace correlation is resolved in this order:

1. 로그에 다음이 포함된 경우spanId 에 대해 브리지에 OTEL Span이 있으면 로그는 해당 Span에 저장된 OTEL 컨텍스트에서 내보내집니다.
2. 그렇지 않은 경우 로그가 전달되면traceId and spanId, 해당 ID가 내보낸 로그 레코드의 에 첨부됩니다. SpanContext.
3. 그렇지 않으면 현재 활성화된 OTEL 컨텍스트에서 로그가 내보내집니다.

그렇지 않은 경우LoggerProvider 이 전역으로 등록되지 않은 경우 내보내기 작업은 아무 동작도 하지 않으며 오류도 발생하지 않습니다.

flush

async flush(): Promise<void>

지원하는 경우 전역 OTEL 추적 프로그램 공급자 및 로거 공급자를 강제로 플러시합니다.forceFlush. 런타임이 종료되기 전에 텔레메트리를 모두 전송해야 하는 서버리스 환경에서 유용합니다.

shutdown

async shutdown(): Promise<void>

브리지를 종료하고 리소스를 정리합니다. 제대로 닫히지 않은 모든 범위를 종료합니다.

사용 예

기본 사용법

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 },
})

수출업체와 결합

브릿지는 수출업체와 함께 사용될 수 있습니다. 브리지는 OTEL 컨텍스트를 처리하는 반면 내보내기는 데이터를 추가 대상으로 보냅니다.

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설정 요구 사항

OtelBridge가 작동하려면 활성 OpenTelemetry SDK가 필요합니다. 브리지는 OTEL의 주변 컨텍스트에서 읽습니다.

참조OtelBridge Guide 에서 OTEL 계측을 구성하고 애플리케이션을 실행하는 방법을 포함한 전체 설정 지침을 확인하세요.

태그 지원

OtelBridge는 분류 및 필터링을 위한 추적 태깅을 지원합니다. 태그는 루트 스팬에만 적용되며mastra.tags attribute on native OTEL spans.

용법

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

태그가 저장되는 방법

태그는 JSON 문자열 배열로 저장됩니다.mastra.tags span attribute:

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

이 형식은 모든 OTEL 호환 백엔드 및 수집기와의 호환성을 보장합니다.

관련된

• 오텔브릿지 가이드: 예시가 포함된 설정 가이드
• 추적 개요: 일반적인 추적 개념
• OtelExporter 참조: 추적 전송을 위한 OTEL 내보내기