> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# OpenTelemetry 내보내기

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

> **양방향 OTEL 통합을 찾고 계신가요?:** 기존 OpenTelemetry 계측이 있고 Mastra 추적이 활성 OTEL 범위에서 컨텍스트를 상속하도록 하려면 다음을 참조하세요.[OpenTelemetry Bridge](https://mastra.zisheng.pro/ko/docs/observability/integrations/bridges/otel) instead.

## 설치

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

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

### 을 위한`gRPC` Providers (Dash0, Datadog)

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
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](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra)는 `/v1/traces` OTLP 엔드포인트를 통해 네이티브 Mastra Trace를 지원합니다. HTTP/Protobuf와 함께 `custom` Provider를 사용하고, Trace가 올바른 MLflow 실험으로 라우팅되도록 실험 헤더를 포함하세요.

```typescript
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](https://latitude.so)는 OTLP Trace를 수집하는 오픈 소스 LLM Observability 및 평가 플랫폼입니다. Latitude의 수집 엔드포인트를 가리키고 API 키와 프로젝트 슬러그로 인증하도록 HTTP/Protobuf와 함께 `custom` Provider를 사용하세요.

```typescript
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](https://console.latitude.so/login)에서 가입하거나, 자체 호스팅한 뒤 엔드포인트가 자체 수집 호스트를 가리키도록 설정하세요.

### 원격 측정.dev

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

```bash
TELEMETRY_DEV_API_KEY=td_live_...
```

```typescript
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](https://www.dash0.com/)자동 통찰력으로 실시간 Observability을 제공합니다.

#### 제로 구성 설정

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

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

# Optional
DASH0_DATASET=production
```

```typescript
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: {} } })],
      },
    },
  }),
})
```

#### 명시적 구성

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

[시그노즈](https://signoz.io/)추적 지원이 내장된 오픈 소스 APM 대안입니다.

#### 제로 구성 설정

```bash
# Required
SIGNOZ_API_KEY=your-api-key

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

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

#### 명시적 구성

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

### 새로운 유물

[새로운 유물](https://newrelic.com/)AI 모니터링 기능으로 완벽한 관찰성을 제공합니다.

#### 제로 구성 설정

```bash
# Required
NEW_RELIC_LICENSE_KEY=your-license-key

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

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

#### 명시적 구성

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

### Traceloop

[Traceloop](https://www.traceloop.com/)자동 Prompt 추적을 통한 LLM Observability을 전문으로 합니다.

#### 제로 구성 설정

```bash
# Required
TRACELOOP_API_KEY=your-api-key

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

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

#### 명시적 구성

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

### 층류

[층류](https://laminar.sh/)전문적인 LLM Observability 및 분석을 제공합니다.

#### 제로 구성 설정

```bash
# Required
LMNR_PROJECT_API_KEY=your-api-key

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

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

#### 명시적 구성

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

> **Laminar-Native 내보내기:** Laminar 대시보드의 네이티브 스팬 경로, 메타데이터 및 태그 렌더링과 같은 Laminar 전용 기능이 필요하다면 전용 [`@mastra/laminar`](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/laminar) 내보내기를 대신 사용하세요. 이 내보내기는 Laminar 플랫폼에 최적화된 통합을 제공합니다.

### 데이터독

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

Datadog은 OTLP 수집에 gRPC를 사용합니다. 올바르게 작동하려면 명시적인 가져오기와 [번들러 구성](https://mastra.zisheng.pro/ko/reference/configuration)이 필요합니다.

```typescript
// 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`:
>
> ```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`](https://mastra.zisheng.pro/ko/reference/configuration)를 구성해야 합니다. 이렇게 하지 않으면 연결 문제가 발생할 수 있습니다.

> **Datadog 네이티브 내보내기:** 자동 스팬 유형 매핑, LLM 스팬 분류, gRPC 구성 없이 간소화된 설정과 같은 Datadog 전용 기능이 필요하다면 전용 [`@mastra/datadog`](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/datadog) 내보내기를 대신 사용하세요. 이 내보내기는 Datadog APM 플랫폼에 최적화된 통합을 제공합니다.

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

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

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

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

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

**npm**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

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

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

## 구성 옵션

### 완전한 구성

```typescript
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](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)을 따르므로 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    | 다양함           | 수집기에 따라 다름                                 |

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

## 문제 해결

### 누락된 종속성 오류

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

```text
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 키와 헤더가 올바른지 확인하세요.

## 관련된

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [OpenTelemetry 브리지](https://mastra.zisheng.pro/ko/docs/observability/integrations/bridges/otel)
- [GenAI v1.38.0에 대한 OpenTelemetry 의미 규칙](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
- [OTEL 수출업체 참조](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/otel)