MastraPlatform수출자

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

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

노트

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

건설자

new MastraPlatformExporter(config?: MastraPlatformExporterConfig)

MastraPlatformExporterConfig

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입니다.

속성

readonly name = 'mastra-platform-exporter';

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

행동 양식

exportTracingEvent

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

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

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

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

onLogEvent

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

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

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

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

onMetricEvent

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

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

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

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

onScoreEvent

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

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

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

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

onFeedbackEvent

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

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

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

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

플러시

async flush(): Promise<void>

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

일시 휴업

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을 펼쳐 넣어 원본 필드 이름을 보존하고, 그 위에 플랫폼 친화적인 별칭 몇 개를 추가합니다.

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에 관한 내용은 인터페이스를 참조하세요.

용법

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

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

// 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는 변경 없이 유지됩니다.

또한보십시오

선적 서류 비치

• 추적 개요: 전체 가이드
• 수출업체: 수출업체 개념

기타 수출업체

• MastraStorage수출업체: 저장 지속성
• 콘솔 내보내기: 디버그 출력
• 랭퓨즈: Langfuse 통합
• 브레인트러스트: Braintrust 통합

참조

• 구성: 구성 옵션
• 인터페이스: 유형 정의