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

# MastraPlatform수출자

**추가된 항목:** `@mastra/observability@1.12.0`. 이전 릴리스(`@mastra/observability@1.8.0`\~을 통해`1.11.x`) 더 이상 사용되지 않는 것과 동일한 내보내기를 내 보냅니다.`CloudExporter`.

온라인 시각화 및 모니터링을 위해 추적 범위, 로그, 메트릭, 점수 및 피드백을 Mastra 플랫폼으로 보냅니다.

> **노트:** `MastraPlatformExporter`의 이전 이름은 `CloudExporter`였습니다. 기존 import가 계속 작동하도록 원래 `CloudExporter` 클래스도 `@mastra/observability`에서 계속 내보내지만, 이 클래스는 더 이상 사용되지 않으며 향후 메이저 버전에서 제거될 예정입니다. 새 코드에서는 `MastraPlatformExporter`를 사용해야 합니다.

## 건설자

```typescript
new MastraPlatformExporter(config?: MastraPlatformExporterConfig)
```

## `MastraPlatformExporterConfig`

```typescript
interface MastraPlatformExporterConfig extends BaseExporterConfig {
  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
  maxBatchSize?: number

  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number

  /** Maximum retry attempts. Default: 3 */
  maxRetries?: number

  /** Mastra Observability access token (from env or config) */
  accessToken?: string

  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
  projectId?: string

  /** Base observability endpoint */
  endpoint?: string

  /** Explicit traces endpoint override */
  tracesEndpoint?: string

  /** Explicit logs endpoint override */
  logsEndpoint?: string

  /** Explicit metrics endpoint override */
  metricsEndpoint?: string

  /** Explicit scores endpoint override */
  scoresEndpoint?: string

  /** Explicit feedback endpoint override */
  feedbackEndpoint?: string
}
```

`BaseExporterConfig`를 확장하며, 포함되는 항목은 다음과 같습니다.

- `logger?: IMastraLogger`- 로거 인스턴스
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'`- 로그 수준(기본값: INFO)

## 환경변수

내보내기는 구성에 제공되지 않은 경우 다음 환경 변수를 읽습니다.

- `MASTRA_PLATFORM_ACCESS_TOKEN` - `MastraPlatformExporter` 요청의 인증 토큰
- `MASTRA_PROJECT_ID` - `/projects/:projectId/ai/spans/publish`와 같은 프로젝트 범위 수집기 경로를 파생할 때 사용할 프로젝트 ID
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - Observability 엔드포인트 재정의 값입니다. 기본 원본 URL 또는 전체 Trace 게시 URL을 전달합니다. `@mastra/observability@1.9.2` 이상에서 기본값은 `https://observability.mastra.ai`입니다.

## 속성

```typescript
readonly name = 'mastra-platform-exporter';
```

더 이상 사용되지 않는 `CloudExporter` 클래스는 이전 버전과의 호환성을 위해 계속 `'mastra-cloud-observability-exporter'`를 `name`으로 사용합니다.

## 행동 양식

### `exportTracingEvent`

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

Mastra 플랫폼으로 내보내기 위한 추적 이벤트를 처리합니다.

`SPAN_ENDED` tracing 이벤트만 내보냅니다. `SPAN_STARTED`와 `SPAN_UPDATED`는 무시합니다. 조건에 맞는 span은 버퍼링되었다가 다음 플러시에서 Trace 엔드포인트로 업로드됩니다.

**반환:** tracing 이벤트가 버퍼링 대상으로 수락되거나 무시된 후의 `Promise<void>`입니다.

### `onLogEvent`

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

내보내기를 위해 로그 신호를 처리합니다.

이 핸들러에 전달된 모든 `LogEvent`는 버퍼링되어 구성된 기본 엔드포인트에서 파생된 로그 엔드포인트로 내보내집니다. tracing과 달리 `MastraPlatformExporter` 수준에서 추가 이벤트 상태 필터링을 수행하지 않습니다. exporter가 비활성화되어 있으면 이 메서드는 아무 작업도 하지 않습니다.

**반환:** 로그 이벤트가 버퍼링 대상으로 수락된 후의 `Promise<void>`입니다.

### `onMetricEvent`

```typescript
async onMetricEvent(event: MetricEvent): Promise<void>
```

내보내기를 위해 메트릭 신호를 처리합니다.

이 핸들러에 전달된 모든 `MetricEvent`는 버퍼링되어 구성된 기본 엔드포인트에서 파생된 메트릭 엔드포인트로 내보내집니다. `MastraPlatformExporter` 내부에서는 메트릭 하위 유형이나 상태에 따른 추가 필터링을 수행하지 않습니다. exporter가 비활성화되어 있지 않으면 수신한 모든 메트릭 이벤트를 전달합니다.

**반환:** 메트릭 이벤트가 버퍼링 대상으로 수락된 후의 `Promise<void>`입니다.

### `onScoreEvent`

```typescript
async onScoreEvent(event: ScoreEvent): Promise<void>
```

내보내기 위한 점수 신호를 처리합니다.

이 핸들러에 전달된 모든 `ScoreEvent`는 버퍼링되어 구성된 기본 엔드포인트에서 파생된 점수 엔드포인트로 내보내집니다. exporter 계층에서는 exporter 비활성화 여부 확인 외에 추가 필터링을 수행하지 않으므로 이 메서드가 수신한 모든 점수 이벤트가 전달됩니다.

**반환:** 점수 이벤트가 버퍼링 대상으로 수락된 후의 `Promise<void>`입니다.

### `onFeedbackEvent`

```typescript
async onFeedbackEvent(event: FeedbackEvent): Promise<void>
```

내보내기를 위한 피드백 신호를 처리합니다.

이 핸들러에 전달된 모든 `FeedbackEvent`는 버퍼링되어 구성된 기본 엔드포인트에서 파생된 피드백 엔드포인트로 내보내집니다. `MastraPlatformExporter` 내부에서는 피드백 유형을 필터링하지 않습니다. exporter가 비활성화되어 있지 않으면 여기서 수신한 모든 피드백 이벤트를 전달합니다.

**반환:** 피드백 이벤트가 버퍼링 대상으로 수락된 후의 `Promise<void>`입니다.

### 플러시

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

Force는 내보내기를 종료하지 않고 버퍼링된 이벤트를 Mastra 플랫폼으로 플러시합니다. 런타임이 종료되기 전에 범위를 내보내야 하는 서버리스 환경에 유용합니다.

### 일시 휴업

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

남은 이벤트를 플러시하고 정리를 수행합니다.

## 행동

### 입증

구성 또는 환경 변수를 통해 액세스 토큰이 제공되지 않으면 내보내기는 다음을 수행합니다.

- 가입 정보와 함께 경고를 기록합니다.
- 무작동으로 작동(모든 이벤트 삭제)

### 일괄 처리

내보내기는 효율적인 네트워크 사용을 위해 추적 범위, 로그, 측정항목, 점수 및 피드백을 일괄 처리합니다.

- 버퍼링된 전체 이벤트 수가 `maxBatchSize`에 도달하면 플러시합니다.
- 배치의 첫 번째 신호가 버퍼링된 후 `maxBatchWaitMs`가 경과하면 플러시합니다.
- `shutdown()` 호출 시 플러시합니다.

### 오류 처리

- 지수 백오프 재시도를 사용합니다.`maxRetries` attempts
- 모든 재시도가 실패한 후 배치를 삭제합니다.
- 오류를 기록하지만 계속해서 새 이벤트를 처리합니다.

`MastraPlatformExporter`에서 발생한 오류는 `MASTRA_PLATFORM_EXPORTER_*` `id` 접두사를 사용합니다. 더 이상 사용되지 않는 `CloudExporter`는 계속 `CLOUD_EXPORTER_*` `id`를 내보냅니다.

### 엔드포인트 라우팅

- 기본 원본 URL에서는 신호 엔드포인트가 자동으로 파생됩니다.
- `projectId`가 없으면 파생 경로로 `/ai/{signal}/publish`를 사용합니다.
- `projectId` 또는 `MASTRA_PROJECT_ID`가 있으면 파생 경로로 `/projects/:projectId/ai/{signal}/publish`를 사용합니다.
- 명시적인 전체 게시 URL은 `projectId`가 구성되어 있어도 그대로 사용됩니다.

### 신호 처리

- `exportTracingEvent()`는 `SPAN_ENDED` tracing 이벤트만 내보냅니다.
- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, `onFeedbackEvent()`는 각 신호 유형에 대해 수신하는 모든 이벤트를 버퍼링합니다.
- 지원되는 모든 신호 배치는 `flush()` 및 `shutdown()` 중에 해당 게시 엔드포인트로 업로드됩니다.

## 스팬 와이어 형식

Mastra 플랫폼으로 전송되는 각 span의 형태는 참조용으로만 여기에 문서화되어 있습니다. 이는 `@mastra/observability` 내부용이므로 import해서는 안 됩니다. exporter는 원본 `AnyExportedSpan`을 펼쳐 넣어 원본 필드 이름을 보존하고, 그 위에 플랫폼 친화적인 별칭 몇 개를 추가합니다.

```typescript
type MastraPlatformSpanRecord = AnyExportedSpan & {
  // Aliases derived from the source span
  spanId: string // alias for span.id
  spanType: string // alias for span.type
  startedAt: Date // alias for span.startTime
  endedAt: Date | null // alias for span.endTime ?? null
  error: AnyExportedSpan['errorInfo'] | null

  // Stamped at export time
  createdAt: Date
  updatedAt: Date | null
}
```

펼쳐진 `AnyExportedSpan`에는 원본 `id`, `type`, `name`, `traceId`, `parentSpanId`, `isRootSpan`, `isEvent`, `startTime`, `endTime`, `entityType`, `entityId`, `entityName`, `tags`, `attributes`, `metadata`, `input`, `output`, `errorInfo`도 포함됩니다. `AnyExportedSpan`에 관한 내용은 [인터페이스](https://mastra.zisheng.pro/ko/reference/observability/tracing/interfaces)를 참조하세요.

## 용법

```typescript
import { MastraPlatformExporter } from '@mastra/observability'

// Uses environment variable for token
const exporter = new MastraPlatformExporter()

// Explicit configuration
const customExporter = new MastraPlatformExporter({
  accessToken: 'your-token',
  projectId: 'project_123',
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  logLevel: 'debug',
})
```

## 다음에서 마이그레이션 중`CloudExporter`

두 클래스 모두 동일한 생성자 서명, 환경 변수 및 동작을 공유합니다. 마이그레이션하려면 가져오기 및 생성자를 바꾸세요.

```typescript
// Before
import { CloudExporter } from '@mastra/observability'
const exporter = new CloudExporter()

// After
import { MastraPlatformExporter } from '@mastra/observability'
const exporter = new MastraPlatformExporter()
```

이전 `CLOUD_EXPORTER_*` 오류 ID 또는 `mastra-cloud-observability-exporter` exporter 이름과 일치하는 대시보드나 알림 규칙이 마이그레이션할 때까지 계속 작동하도록 원본 `CloudExporter`는 변경 없이 유지됩니다.

## 또한보십시오

### 선적 서류 비치

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview): 전체 가이드
- [수출업체](https://mastra.zisheng.pro/ko/docs/observability/integrations/overview): 수출업체 개념

### 기타 수출업체

- [MastraStorage수출업체](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/mastra-storage-exporter): 저장 지속성
- [콘솔 내보내기](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/console-exporter): 디버그 출력
- [랭퓨즈](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/langfuse): Langfuse 통합
- [브레인트러스트](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/braintrust): Braintrust 통합

### 참조

- [구성](https://mastra.zisheng.pro/ko/reference/observability/tracing/configuration): 구성 옵션
- [인터페이스](https://mastra.zisheng.pro/ko/reference/observability/tracing/interfaces): 유형 정의