Mastra Storage 수출업체

그만큼MastraStorageExporter구성된 저장소 백엔드에 대한 추적을 유지하여 Studio를 통해 액세스할 수 있도록 합니다. 외부 서비스가 필요하지 않습니다.

노트

MastraStorageExporter이전에 호출되었습니다DefaultExporter. The original DefaultExporter클래스는 여전히 다음에서 내보내집니다.@mastra/observability이전 버전과의 호환성을 위해 더 이상 사용되지 않습니다. 새로운 코드는 다음을 사용해야 합니다.MastraStorageExporter.

:::warning[생산 Observability] Observability 데이터는 프로덕션 환경에서 범용 데이터베이스를 빠르게 압도할 수 있습니다. 트래픽이 많은 애플리케이션의 경우 관찰성 스토리지 도메인을 다음으로 라우팅합니다.ClickHouse through composite storage. See Production Recommendations for details. :::

구성

전제조건

1. 스토리지 백엔드: 스토리지 공급자(libSQL, PostgreSQL 등)를 구성합니다.
2. 사진관: 로컬에서 추적을 보기 위해 설치

기본 설정

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db', // Required for trace persistence
  }),
  observability: new Observability({
    configs: {
      local: {
        serviceName: 'my-service',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

권장 구성

Observability 구성에 MastraStorageExporter를 포함합니다.

import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (requires MASTRA_PLATFORM_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

사진관

Studio를 통해 추적에 액세스합니다.

1. 스튜디오 시작
2. Observability으로 이동
3. 지역 흔적 필터링 및 검색
4. 자세한 SPAN 정보 확인

추적 전략

MastraStorageExporter는 스토리지 공급자를 기반으로 최적의 추적 전략을 자동으로 선택합니다. 필요한 경우 이 선택을 재정의할 수도 있습니다.

사용 가능한 전략

전략	설명	사용 사례
realtime	각 이벤트를 즉시 처리	개발, 디버깅, 적은 트래픽
batch-with-updates	전체 수명 주기를 지원하며 이벤트를 버퍼링하고 일괄 쓰기	트래픽이 적은 프로덕션 환경
insert-only	완료된 스팬만 처리하고 업데이트는 무시	트래픽이 많은 프로덕션 환경

전략 구성

new MastraStorageExporter({
  strategy: 'auto', // Default - let storage provider decide
  // or explicitly set:
  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'

  // Batching configuration (applies to both batch-with-updates and insert-only)
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before flushing
  maxBufferSize: 10000, // Max spans to buffer
})

스토리지 Provider 지원

다양한 스토리지 공급자는 다양한 추적 전략을 지원합니다. 일부 공급자는 프로덕션 워크로드에 대한 Observability을 지원하는 반면 다른 공급자는 주로 로컬 개발을 위한 것입니다.

전략을 다음과 같이 설정하면'auto', the MastraStorageExporter 은 스토리지 Provider에 가장 적합한 전략을 자동으로 선택합니다. 스토리지 Provider가 지원하지 않는 전략을 명시적으로 설정하면 익스포터는 경고를 기록하고 Provider가 선호하는 전략으로 대체합니다.

Observability 지원 Provider

스토리지 제공자	선호하는 전략	지원되는 전략	권장 용도
ClickHouse	insert-only	insert-only	Production (high-volume)
PostgreSQL	batch-with-updates	batch-with-updates, insert-only	Production (low volume)
MSSQL	batch-with-updates	batch-with-updates, insert-only	Production (low volume)
MongoDB	batch-with-updates	batch-with-updates, insert-only	Production (low volume)
OracleDB	batch-with-updates	batch-with-updates, insert-only	Production (low volume)
libSQL	batch-with-updates	batch-with-updates, insert-only	기본 스토리지, 개발에 적합

Observability 지원이 없는 공급자

다음 스토리지 Providerdon't support 은 Observability 도메인을 지원하지 않습니다. 이러한 Provider 중 하나를 사용하면서 Observability가 필요하다면 composite storage 을 사용하여 Observability 데이터를 지원되는 Provider로 라우팅하세요.

• 볼록한
• DynamoDB
• 클라우드플레어 D1
• Cloudflare 내구성 개체
• 업스태시
• 랜스DB

전략 이점

• 실시간: 즉각적인 가시성, 디버깅에 가장 적합
• 일괄 업데이트: 처리량 10~100배 향상, 전체 수명주기
• 삽입 전용: 데이터베이스 운영을 70% 추가로 줄여 분석에 적합

생산 권장 사항

관측 가능성 데이터는 프로덕션 환경에서 빠르게 증가합니다. 단일 Agent 상호 작용으로 수백 개의 범위가 생성될 수 있으며 트래픽이 많은 애플리케이션은 하루에 수천 개의 추적을 생성할 수 있습니다. 대부분의 범용 데이터베이스는 쓰기 중심의 추가 전용 워크로드에 최적화되어 있지 않습니다.

권장 사항: 대량 생산을 위한 ClickHouse

클릭하우스대용량 분석 워크로드를 위해 설계된 컬럼형 데이터베이스입니다. 다음과 같은 이유로 프로덕션 Observability을 위해 권장되는 선택입니다.

• 쓰기에 최적화됨: 초당 수백만 개의 삽입을 처리합니다.
• 효율적인 압축: 추적 데이터 저장 비용 절감
• 빠른 쿼리: 컬럼형 스토리지를 통해 빠른 추적 조회 및 집계가 가능합니다.
• 시계열 네이티브: 시간 기반 데이터 보존 및 파티셔닝 지원 내장

복합 스토리지 사용

관측 가능성을 지원하지 않는 공급자(예: Convex 또는 DynamoDB)를 사용 중이거나 성능을 최적화하려는 경우 다음을 사용하세요.composite storage 을 사용하여 다른 데이터는 기본 데이터베이스에 유지하면서 Observability 데이터를 ClickHouse로 라우팅하세요.

일괄 처리 동작

플러시 트리거

두 배치 전략 모두에 대해(batch-with-updates and insert-only)인 경우 다음 조건 중 하나라도 충족되면 Trace가 스토리지로 플러시됩니다.

1. 크기 트리거: 버퍼 도달maxBatchSize spans
2. 시간 트리거: maxBatchWaitMs elapsed since first event
3. 비상 플러시: 버퍼 접근maxBufferSize limit
4. 일시 휴업: 보류 중인 모든 이벤트를 강제로 플러시합니다.

오류 처리

MastraStorageExporter에는 프로덕션 사용을 위한 안정적인 오류 처리 기능이 포함되어 있습니다.

• 재시도 로직: 지수 백오프(500ms, 1s, 2s, 4s)
• 일시적인 오류: 백오프를 통한 자동 재시도
• 지속적인 실패: 4번의 시도 실패 후 배치 삭제
• 버퍼 오버플로: 스토리지 중단 시 Memory 문제 방지

삭제된 관측 가능성 이벤트

DefaultExporter관측 가능성 데이터를 유지할 수 없는 경우 구조화된 드롭 이벤트를 내보냅니다. 수출업자 또는 교량 등록onDroppedEvent 을 사용하여 이러한 삭제 이벤트를 알림 또는 모니터링 시스템으로 전달하세요.

이벤트가 삭제되는 두 가지 이유는 다음과 같습니다.

• unsupported-storage: 저장소 공급자가 신호 유형을 구현하지 않습니다.
• retry-exhausted: 내보내기가 최대 배치를 재시도했습니다.maxRetries times and then dropped it.

다음 예에서는 모니터링 엔드포인트에 삭제 세부 정보를 전달하는 방법을 보여줍니다.

src/mastra/observability.ts

import { BaseExporter } from '@mastra/observability'
import type { ObservabilityDropEvent, TracingEvent } from '@mastra/core/observability'

class DropAlertExporter extends BaseExporter {
  name = 'drop-alerts'

  async onDroppedEvent(event: ObservabilityDropEvent) {
    await fetch('https://monitoring.example.com/observability-drops', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        count: event.count,
        signal: event.signal,
        reason: event.reason,
        exporterName: event.exporterName,
      }),
    })
  }

  protected async _exportTracingEvent(_event: TracingEvent) {}
}

구성 예

// Zero config - recommended for most users
new MastraStorageExporter()

// Development override
new MastraStorageExporter({
  strategy: 'realtime', // Immediate visibility for debugging
})

// High-throughput production
new MastraStorageExporter({
  maxBatchSize: 2000, // Larger batches
  maxBatchWaitMs: 10000, // Wait longer to fill batches
  maxBufferSize: 50000, // Handle longer outages
})

// Low-latency production
new MastraStorageExporter({
  maxBatchSize: 100, // Smaller batches
  maxBatchWaitMs: 1000, // Flush quickly
})

관련된

• 추적 개요
• MastraPlatform수출자
• 복합 스토리지: 여러 스토리지 Provider 결합
• 스토리지 구성