OpenTelemetry 내보내기

OpenTelemetry(OTEL) 내보내기는 표준화된 GenAI용 OpenTelemetry 시맨틱 규칙을 사용하여 모든 OTEL 호환 Observability 플랫폼에 Trace와 로그를 전송합니다. 따라서 Datadog, New Relic, SigNoz, MLflow, Latitude, Dash0, Traceloop, Laminar, telemetry.dev 등의 플랫폼과 폭넓게 호환됩니다.

양방향 OTEL 통합을 찾고 계신가요?

기존 OpenTelemetry 계측이 있고 Mastra 추적이 활성 OTEL 범위에서 컨텍스트를 상속하도록 하려면 다음을 참조하세요.OpenTelemetry Bridge instead.

설치

각 공급자에는 특정 프로토콜 패키지가 필요합니다. 기본 내보내기와 공급자용 프로토콜 패키지를 설치합니다.

HTTP/Protobuf Provider(SigNoz, New Relic, Laminar, MLflow, Latitude, telemetry.dev)

npm

npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

pnpm

pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

Yarn

yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

Bun

bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

을 위한gRPC Providers (Dash0, Datadog)

npm

npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js

pnpm

pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js

Yarn

yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js

Bun

bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js

HTTP/JSON 공급자의 경우(Traceloop)

npm

npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http

pnpm

pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http

Yarn

yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http

Bun

bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http

환경변수

모든 공급자는 환경 변수를 통해 제로 구성 설정을 지원합니다. 적절한 변수를 설정하면 내보내기가 자동으로 해당 변수를 사용합니다.

공급자	환경 변수
대시0	DASH0_API_KEY (required), DASH0_ENDPOINT (required), DASH0_DATASET (optional)
SigNoz	SIGNOZ_API_KEY (required), SIGNOZ_REGION (optional), SIGNOZ_ENDPOINT (optional)
New Relic	NEW_RELIC_LICENSE_KEY(필수의),NEW_RELIC_ENDPOINT(선택사항)
트레이스루프	TRACELOOP_API_KEY(필수의),TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINT(선택사항)
층류	LMNR_PROJECT_API_KEY(필수의),LAMINAR_ENDPOINT(선택사항)

공급자 구성

MLflow

MLflow는 /v1/traces OTLP 엔드포인트를 통해 네이티브 Mastra Trace를 지원합니다. HTTP/Protobuf와 함께 custom Provider를 사용하고, Trace가 올바른 MLflow 실험으로 라우팅되도록 실험 헤더를 포함하세요.

src/mastra/index.ts

new OtelExporter({
  provider: {
    custom: {
      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
      protocol: 'http/protobuf',
      headers: {
        'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID,
      },
    },
  },
})

위도

Latitude는 OTLP Trace를 수집하는 오픈 소스 LLM Observability 및 평가 플랫폼입니다. Latitude의 수집 엔드포인트를 가리키고 API 키와 프로젝트 슬러그로 인증하도록 HTTP/Protobuf와 함께 custom Provider를 사용하세요.

src/mastra/index.ts

new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.latitude.so/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`,
        'X-Latitude-Project': process.env.LATITUDE_PROJECT,
      },
    },
  },
})

console.latitude.so에서 가입하거나, 자체 호스팅한 뒤 엔드포인트가 자체 수집 호스트를 가리키도록 설정하세요.

원격 측정.dev

telemetry.dev는 OTLP/HTTP protobuf Trace를 수집하고 OpenTelemetry GenAI 의미 체계 규칙을 Model, Provider, 토큰, 지연 시간 및 비용 필드로 정규화합니다. 프로젝트 API 키와 함께 custom Provider를 사용하세요.

.env

TELEMETRY_DEV_API_KEY=td_live_...

src/mastra/index.ts

new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.telemetry.dev/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`,
      },
    },
  },
})

대시0

대시0자동 통찰력으로 실시간 Observability을 제공합니다.

제로 구성 설정

환경 변수를 설정하고 빈 구성으로 내보내기를 사용합니다.

.env

# Required
DASH0_API_KEY=your-api-key
DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317

# Optional
DASH0_DATASET=production

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: 'my-service',
        exporters: [new OtelExporter({ provider: { dash0: {} } })],
      },
    },
  }),
})

명시적 구성

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              dash0: {
                apiKey: process.env.DASH0_API_KEY,
                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
                dataset: 'production', // Optional dataset name
              },
            },
            resourceAttributes: {
              // Optional OpenTelemetry Resource Attributes for the trace
              ['deployment.environment']: 'dev',
            },
          }),
        ],
      },
    },
  }),
})

정보

대시보드에서 Dash0 엔드포인트를 가져옵니다. 형식으로 되어 있어야 합니다.ingress.{region}.aws.dash0.com:4317.

SigNoz

시그노즈추적 지원이 내장된 오픈 소스 APM 대안입니다.

제로 구성 설정

.env

# Required
SIGNOZ_API_KEY=your-api-key

# Optional
SIGNOZ_REGION=us  # 'us' | 'eu' | 'in'
SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted

src/mastra/index.ts

new OtelExporter({ provider: { signoz: {} } })

명시적 구성

src/mastra/index.ts

new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us', // 'us' | 'eu' | 'in'
      // endpoint: 'https://my-signoz.example.com', // For self-hosted
    },
  },
})

새로운 유물

새로운 유물AI 모니터링 기능으로 완벽한 관찰성을 제공합니다.

제로 구성 설정

.env

# Required
NEW_RELIC_LICENSE_KEY=your-license-key

# Optional
NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region

src/mastra/index.ts

new OtelExporter({ provider: { newrelic: {} } })

명시적 구성

src/mastra/index.ts

new OtelExporter({
  provider: {
    newrelic: {
      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
    },
  },
})

Traceloop

Traceloop자동 Prompt 추적을 통한 LLM Observability을 전문으로 합니다.

제로 구성 설정

.env

# Required
TRACELOOP_API_KEY=your-api-key

# Optional
TRACELOOP_DESTINATION_ID=my-destination
TRACELOOP_ENDPOINT=https://custom.traceloop.com

src/mastra/index.ts

new OtelExporter({ provider: { traceloop: {} } })

명시적 구성

src/mastra/index.ts

new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: 'my-destination', // Optional
    },
  },
})

층류

층류전문적인 LLM Observability 및 분석을 제공합니다.

제로 구성 설정

.env

# Required
LMNR_PROJECT_API_KEY=your-api-key

# Optional
LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces

src/mastra/index.ts

new OtelExporter({ provider: { laminar: {} } })

명시적 구성

src/mastra/index.ts

new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
    },
  },
})

Laminar-Native 내보내기

Laminar 대시보드의 네이티브 스팬 경로, 메타데이터 및 태그 렌더링과 같은 Laminar 전용 기능이 필요하다면 전용 @mastra/laminar 내보내기를 대신 사용하세요. 이 내보내기는 Laminar 플랫폼에 최적화된 통합을 제공합니다.

데이터독

데이터독APM은 분산 추적을 통해 애플리케이션 성능 모니터링을 제공합니다. OTLP를 통해 Datadog에 추적을 보내려면 OTLP 수집이 활성화된 상태에서 실행되는 Datadog Agent가 필요합니다.

Datadog은 OTLP 수집에 gRPC를 사용합니다. 올바르게 작동하려면 명시적인 가져오기와 번들러 구성이 필요합니다.

src/mastra/index.ts

// Explicitly import gRPC dependencies for the bundler
import '@grpc/grpc-js'
import '@opentelemetry/exporter-trace-otlp-grpc'
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter, type ExportProtocol } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  // Add grpc-js to externals so it's handled at runtime
  bundler: {
    externals: ['@grpc/grpc-js'],
  },
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
                protocol: (process.env.OTEL_EXPORTER_OTLP_PROTOCOL || 'grpc') as ExportProtocol,
                headers: {},
              },
            },
          }),
        ],
      },
    },
  }),
})

정보

Datadog Agent는 OTLP 수집이 활성화된 상태로 구성되어야 합니다. 다음을 추가하세요.datadog.yaml:

otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

Datadog Agent를 로컬에서 실행할 때 기본 OTLP 엔드포인트는 http://localhost:4317입니다.

경고

gRPC 전송이 올바르게 작동하려면 파일 상단에서 @grpc/grpc-js 및 @opentelemetry/exporter-trace-otlp-grpc를 명시적으로 가져오고 bundler.externals를 구성해야 합니다. 이렇게 하지 않으면 연결 문제가 발생할 수 있습니다.

Datadog 네이티브 내보내기

자동 스팬 유형 매핑, LLM 스팬 분류, gRPC 구성 없이 간소화된 설정과 같은 Datadog 전용 기능이 필요하다면 전용 @mastra/datadog 내보내기를 대신 사용하세요. 이 내보내기는 Datadog APM 플랫폼에 최적화된 통합을 제공합니다.

사용자 정의/일반 OTEL 엔드포인트

기타 OTEL 호환 플랫폼 또는 사용자 정의 수집기의 경우:

src/mastra/index.ts

new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://your-collector.example.com/v1/traces',
      protocol: 'http/protobuf', // 'http/json' | 'http/protobuf' | 'grpc'
      headers: {
        'x-api-key': process.env.API_KEY,
      },
    },
  },
})

신호

내보내기는 두 개의 OpenTelemetry 신호를 보냅니다.

• Trace: BatchSpanProcessor를 통해 내보내는 Mastra 스팬입니다.
• 로그: BatchLogRecordProcessor를 통해 내보내는 Mastra 로그 이벤트입니다. traceId와 spanId가 포함된 로그는 OTEL 로그 레코드의 네이티브 Trace 컨텍스트와 mastra.traceId / mastra.spanId 속성을 모두 사용해 Trace와 연관되므로, Datadog, Grafana, Honeycomb 같은 백엔드가 로그를 Trace와 자동으로 연결할 수 있습니다. 두 신호는 모두 기본적으로 활성화되며 동일한 Provider 구성을 공유합니다. 로그 엔드포인트는 Trace 엔드포인트의 /v1/traces 접미사를 /v1/logs로 바꿔 파생합니다. 신호를 비활성화하려면signals option:

src/mastra/index.ts

new OtelExporter({
  provider: {/* ... */},
  signals: {
    traces: true, // default
    logs: false, // disable log export
  },
})

로그를 내보내려면 프로토콜에 맞는 OTLP 로그 내보내기 패키지를 설치해야 합니다.

npm

# HTTP/JSON
npm install @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
npm install @opentelemetry/exporter-logs-otlp-proto
# gRPC
npm install @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js

pnpm

# HTTP/JSON
pnpm add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
pnpm add @opentelemetry/exporter-logs-otlp-proto
# gRPC
pnpm add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js

Yarn

# HTTP/JSON
yarn add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
yarn add @opentelemetry/exporter-logs-otlp-proto
# gRPC
yarn add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js

Bun

# HTTP/JSON
bun add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
bun add @opentelemetry/exporter-logs-otlp-proto
# gRPC
bun add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js

일치하는 로그 내보내기 패키지가 설치되어 있지 않으면 로그 내보내기가 자동으로 비활성화되고 추적이 계속 작동합니다.

구성 옵션

완전한 구성

new OtelExporter({
  // Provider configuration (required)
  provider: {
    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
  },

  // Per-signal toggles. Both default to true.
  signals: {
    traces: true,
    logs: true,
  },

  // Export configuration
  timeout: 30000, // Export timeout in milliseconds
  batchSize: 100, // Number of spans/logs per batch

  // Debug options
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
})

OpenTelemetry의미론적 규칙

내보내기는 GenAI용 OpenTelemetry 시맨틱 규칙 v1.38.0을 따르므로 Observability 플랫폼과의 호환성을 보장합니다.

Span 이름 지정

• LLM 운영: chat {model}
• Tool 실행: execute_tool {tool_name}
• Agent 실행: invoke_agent {agent_id}
• Workflow 실행: invoke_workflow {workflow_id}

주요 속성

• gen_ai.operation.name- 작업 유형(채팅, Tool.실행 등)
• gen_ai.provider.name- AI 제공자(openai, Anthropic 등)
• gen_ai.request.model- Model 식별자
• gen_ai.input.messages- Model에게 제공되는 채팅 기록
• gen_ai.output.messages- Model이 반환한 메시지
• gen_ai.usage.input_tokens- 입력 토큰 수
• gen_ai.usage.output_tokens- 출력 토큰 수
• gen_ai.request.temperature- 샘플링 온도
• gen_ai.response.finish_reasons- 완료 이유

프로토콜 선택 가이드

공급자에 따라 올바른 프로토콜 패키지를 선택하십시오.

Provider	프로토콜	필수 패키지
Dash0	gRPC	@opentelemetry/exporter-trace-otlp-grpc
Datadog	gRPC	@opentelemetry/exporter-trace-otlp-grpc
SigNoz	HTTP/Protobuf	@opentelemetry/exporter-trace-otlp-proto
New Relic	HTTP/Protobuf	@opentelemetry/exporter-trace-otlp-proto
Traceloop	HTTP/JSON	@opentelemetry/exporter-trace-otlp-http
Laminar	HTTP/Protobuf	@opentelemetry/exporter-trace-otlp-proto
Custom	다양함	수집기에 따라 다름

경고

공급자에 맞는 올바른 프로토콜 패키지를 설치했는지 확인하세요. 잘못된 패키지가 설치된 경우 내보내기 프로그램에서 유용한 오류 메시지를 제공합니다.

문제 해결

누락된 종속성 오류

다음과 같은 오류가 표시되는 경우:

HTTP/Protobuf exporter is not installed (required for signoz).
To use HTTP/Protobuf export, install the required package:
  npm install @opentelemetry/exporter-trace-otlp-proto

공급자에게 제안된 패키지를 설치합니다.

일반적인 문제

1. 잘못된 프로토콜 패키지: 공급자에 맞는 내보내기 프로그램을 설치했는지 확인하세요.
2. 잘못된 엔드포인트: 엔드포인트 형식이 공급자 요구 사항과 일치하는지 확인하세요.
3. 인증 실패: API 키와 헤더가 올바른지 확인하세요.

관련된

• 추적 개요
• OpenTelemetry 브리지
• GenAI v1.38.0에 대한 OpenTelemetry 의미 규칙
• OTEL 수출업체 참조