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

# 오텔엑스포터

모든 OpenTelemetry 호환 관찰 플랫폼에 추적 및 로그를 보냅니다. 추적은 표준화된 GenAI 의미 체계 규칙을 사용합니다. 로그는 원래 심각도와 메시지 본문을 전달하며 OTEL 로그 레코드의 기본 추적 컨텍스트와 추적을 통해 추적과 상관됩니다.`mastra.traceId` / `mastra.spanId`속성.

## 건설자

```typescript
new OtelExporter(config: OtelExporterConfig)
```

## `OtelExporterConfig`

```typescript
interface OtelExporterConfig {
  provider?: ProviderConfig
  signals?: {
    traces?: boolean
    logs?: boolean
  }
  timeout?: number
  batchSize?: number
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
}
```

## 공급자 구성

### `Dash0Config`

```typescript
interface Dash0Config {
  apiKey?: string
  endpoint?: string
  dataset?: string
}
```

### `SignozConfig`

```typescript
interface SignozConfig {
  apiKey?: string
  region?: 'us' | 'eu' | 'in'
  endpoint?: string
}
```

### `NewRelicConfig`

```typescript
interface NewRelicConfig {
  apiKey?: string
  endpoint?: string
}
```

### `TraceloopConfig`

```typescript
interface TraceloopConfig {
  apiKey?: string
  destinationId?: string
  endpoint?: string
}
```

### `LaminarConfig`

```typescript
interface LaminarConfig {
  apiKey?: string
  endpoint?: string
}
```

### `CustomConfig`

```typescript
interface CustomConfig {
  endpoint: string
  protocol?: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
  headers?: Record<string, string>
}
```

## 행동 양식

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

구성된 OTEL 백엔드로 추적 이벤트를 내보냅니다.

### 플러시

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

강제로 내보내기를 종료하지 않고 버퍼링된 모든 범위를 OTEL 백엔드로 플러시합니다. 런타임이 종료되기 전에 범위를 내보내야 하는 서버리스 환경에 유용합니다.

### 일시 휴업

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

보류 중인 추적을 플러시하고 내보내기를 종료합니다.

## 사용 예

### Zero-Config(환경 변수 사용)

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

// Set SIGNOZ_API_KEY, SIGNOZ_REGION environment variables
const exporter = new OtelExporter({ provider: { signoz: {} } })

// Or for other providers:
// Set DASH0_API_KEY, DASH0_ENDPOINT for Dash0
// Set NEW_RELIC_LICENSE_KEY for New Relic
// Set TRACELOOP_API_KEY for Traceloop
// Set LMNR_PROJECT_API_KEY for Laminar
```

### 명시적 구성

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

const exporter = new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us',
    },
  },
})
```

### 커스텀 엔드포인트 포함

```typescript
const exporter = new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://my-collector.example.com/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        'x-api-key': process.env.API_KEY,
      },
    },
  },
  timeout: 60000,
  logLevel: 'debug',
})
```

## 프로토콜 요구 사항

공급자마다 다른 OTEL 내보내기 패키지가 필요합니다. 추적 및 로그 내보내기는 독립적입니다. 추적만 필요한 경우 추적 패키지만 설치하고, 로그 내보내기도 원하는 경우 선택한 프로토콜에 대한 추적 및 로그 패키지를 모두 설치합니다. Zipkin은 OTLP 로그를 지원하지 않습니다.

| 프로토콜          | 추적 패키지                                                        | 로그 패키지                                                       |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc` (+ `@grpc/grpc-js`) | `@opentelemetry/exporter-logs-otlp-grpc` (+ `@grpc/grpc-js`) |
| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto`                    | `@opentelemetry/exporter-logs-otlp-proto`                    |
| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`                     | `@opentelemetry/exporter-logs-otlp-http`                     |
| Zipkin        | `@opentelemetry/exporter-zipkin`                              | not supported                                                |

## 태그 지원

OtelExporter는 분류 및 필터링을 위한 추적 태그 지정을 지원합니다. 태그는 루트 스팬에만 적용되며`mastra.tags` attribute.

### 용법

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

### 태그가 저장되는 방법

백엔드 호환성을 극대화하기 위해 태그는 `mastra.tags` span 속성에 JSON 문자열 배열로 저장됩니다.

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

:::참고 OpenTelemetry 사양은 기본 배열 속성을 지원하지만 많은 백엔드(Jaeger, Zipkin, Tempo)에서는 배열 지원이 제한되어 있습니다. JSON 문자열은 모든 관찰 플랫폼에서 일관된 동작을 보장합니다. :::

## 관련된

- [OtelExporter 가이드](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/otel): 공급자 구성이 포함된 설정 가이드
- [오텔브릿지](https://mastra.zisheng.pro/ko/docs/observability/integrations/bridges/otel): 양방향 OTEL 컨텍스트 통합용
- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview): 일반적인 추적 개념