클라우드 내보내기

추가된 항목: @mastra/observability@1.8.0. 더 이상 사용되지 않음1.12.0찬성MastraPlatformExporter.

:::warning[사용되지 않음]

CloudExporter는 이전 버전과의 호환성을 위해 유지되며 향후 메이저 버전에서 제거될 예정입니다. 새 프로젝트에서는 MastraPlatformExporter를 사용하세요. 두 클래스는 생성자, 환경 변수, 런타임 동작이 동일합니다. CloudExporter는 기존 mastra-cloud-observability-exporter exporter name과 CLOUD_EXPORTER_* 오류 ID를 유지하므로 이를 기반으로 구성된 모니터링 규칙이 계속 작동합니다. :::

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

건설자

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfig

interface CloudExporterConfig extends BaseExporterConfig {
  /** Maximum number of spans per batch. Default: 1000 */
  maxBatchSize?: number

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

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

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

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

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

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

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

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

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

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

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

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

환경변수

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

• MASTRA_PLATFORM_ACCESS_TOKEN - CloudExporter 요청의 인증 토큰
• 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-cloud-observability-exporter';

행동 양식

exportTracingEvent

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

클라우드 내보내기에 대한 추적 이벤트를 처리합니다.

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

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

onLogEvent

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

클라우드 내보내기를 위한 로그 신호를 처리합니다.

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

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

onMetricEvent

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

클라우드 내보내기를 위한 지표 신호를 처리합니다.

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

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

onScoreEvent

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

클라우드 내보내기에 대한 점수 신호를 처리합니다.

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

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

onFeedbackEvent

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

클라우드 내보내기에 대한 피드백 신호를 처리합니다.

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

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

플러시

async flush(): Promise<void>

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

일시 휴업

async shutdown(): Promise<void>

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

행동

입증

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

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

일괄 처리

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

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

오류 처리

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

엔드포인트 라우팅

• 기본 원본 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() 중에 해당 Cloud 게시 엔드포인트로 업로드됩니다.

MastraCloudSpanRecord

클라우드 범위의 내부 형식:

interface MastraCloudSpanRecord {
  traceId: string
  spanId: string
  parentSpanId: string | null
  name: string
  spanType: string
  attributes: Record<string, any> | null
  metadata: Record<string, any> | null
  startedAt: Date
  endedAt: Date | null
  input: any
  output: any
  error: any
  isEvent: boolean
  createdAt: Date
  updatedAt: Date | null
}

용법

import { CloudExporter } from '@mastra/observability'

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

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

또한보십시오

선적 서류 비치

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

기타 수출업체

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

참조

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