Mastra 플랫폼 수출업체

그만큼MastraPlatformExporter추적, 로그, 메트릭, 점수 및 피드백을 Mastra 플랫폼으로 보냅니다. 이를 사용하여 Mastra 앱의 관측 가능성 데이터를 Mastra 플랫폼의 호스팅 프로젝트로 라우팅합니다.

노트

MastraPlatformExporter는 이전에 CloudExporter라고 불렸습니다. 원래 CloudExporter 클래스는 이전 버전과의 호환성을 위해 여전히 @mastra/observability에서 내보내지만 더 이상 사용되지 않습니다. 새 코드에서는 MastraPlatformExporter를 사용해야 합니다.

:::note[자체 호스팅 또는 독립형 앱]

Mastra 플랫폼이 아닌 자체 인프라에서 Mastra 애플리케이션을 호스팅하는 경우에도 Trace, 로그 및 측정항목을 보려면 배포된 Studio 프로젝트가 필요합니다. MastraPlatformExporter는 데이터를 Studio 프로젝트로 전송하므로 사용 전에 프로젝트가 존재해야 합니다.

1. 아직 없다면 Mastra 프로젝트를 만드세요.
2. mastra studio deploy를 사용해 Studio를 Mastra 플랫폼에 배포하세요.
3. 액세스 토큰을 만들고 프로젝트 ID를 찾으려면 아래의 빠른 시작 단계를 따르세요. :::

버전 호환성

• MastraPlatformExporter는 @mastra/observability@1.12.0부터 사용할 수 있습니다. 1.8.0부터 1.11.x까지는 같은 내보내기가 CloudExporter로만 포함되어 있습니다. 생성자 시그니처와 환경 변수는 동일합니다.
• @mastra/observability@1.8.0부터 1.9.1까지는 MASTRA_PLATFORM_ACCESS_TOKEN 및 MASTRA_PROJECT_ID와 함께 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai를 설정하세요.
• @mastra/observability@1.9.2부터 내보내기의 기본값은 https://observability.mastra.ai이므로, 다른 수집기로 원격 분석을 보내려는 경우에만 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT가 필요합니다.

빠른 시작

MastraPlatformExporter를 연결하려면 액세스 토큰을 만들고 대상 projectId를 찾은 다음 Observability 구성에 내보내기를 추가하세요.

1. 액세스 토큰 생성

다음 명령을 실행하십시오.

mastra auth tokens create exporter-token

이 명령은 다음과 같이 사용할 수 있는 토큰 비밀을 인쇄합니다.MASTRA_PLATFORM_ACCESS_TOKEN.

이미 액세스 토큰이 있다면 Mastra 플랫폼의 Observability 값을 대신 사용하세요. 다음 위치 중 하나에서 찾을 수 있습니다.

• Projects 페이지에서 프로젝트 목록을 열고 프로젝트 카드의 Observability 행을 찾습니다.
• 프로젝트의 Overview 페이지에서 배포 URL 바로 아래에 있는 Observability 행을 찾습니다. 토큰을 환경 변수로 설정합니다.

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>

2. 당신의 것을 찾으세요projectId

다음 명령을 실행하십시오.

mastra studio deploy list

출력은 다음과 유사합니다.

✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud

이 출력에서 ​​괄호 안의 값은projectId:

<your-project-id>

환경 변수로 설정하십시오.

.env

MASTRA_PROJECT_ID=<your-project-id>

3. 환경 변수 설정

MastraPlatformExporter가 인증하고 원격 분석을 올바른 프로젝트로 라우팅할 수 있도록 환경에 두 값을 모두 설정하세요.

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>

@mastra/observability@1.8.0부터 1.9.1까지를 사용하는 경우 Mastra 플랫폼 수집기도 명시적으로 설정하세요.

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai

Mastra 플랫폼 이외의 위치로 원격 분석을 보내려면 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT도 설정하세요. 기본 오리진 또는 /spans/publish로 끝나는 전체 Trace 게시 URL을 전달할 수 있습니다.

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

기본 오리진을 전달하면 MastraPlatformExporter가 Trace, 로그, 측정항목, 점수 및 피드백에 맞는 게시 URL을 자동으로 파생합니다.

4. 활성화MastraPlatformExporter

다음 예제에서는 Observability 구성에 MastraPlatformExporter를 추가하는 방법을 보여 줍니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraPlatformExporter } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'api-server',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})

serviceName은 MastraPlatformExporter 자체가 아니라 Observability 구성에 설정하세요. 안정적인 serviceName 값을 사용하세요. Studio에서는 Deployments → Service Name으로 Trace를 필터링할 수 있으므로 이름을 일관되게 유지하면 Trace를 더 쉽게 찾을 수 있습니다. 전체 Observability 구성 구조는 Observability 구성 레퍼런스를 참조하세요. 원한다면 전적으로 환경 변수에 의존하세요.

src/mastra/index.ts

new MastraPlatformExporter()

MASTRA_PLATFORM_ACCESS_TOKEN과 MASTRA_PROJECT_ID를 설정하면 MastraPlatformExporter가 구성한 Mastra 플랫폼 프로젝트로 데이터를 전송합니다. MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT도 설정하면 대신 해당 수집기로 데이터를 전송합니다. 전체 구성 옵션 목록은 MastraPlatformExporter 레퍼런스를 참조하세요.

권장 구성

Studio에서 로컬 Trace도 검사하거나 Observability 데이터를 구성된 스토리지에 영구 저장하려면 MastraStorageExporter를 포함하세요.

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

완전한 구성

MastraPlatformExporter의 기본 대상은 Mastra 플랫폼입니다. 원격 분석을 다른 수집기로 보내려면 환경에 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT를 설정하거나 코드에서 endpoint를 전달하세요.

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

다음 예에서는 코드에서 수집기 끝점 및 일괄 처리 동작을 재정의하는 방법을 보여줍니다.

src/mastra/index.ts

new MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})

Mastra Studio에서 데이터 보기

MastraPlatformExporter를 활성화한 후 Mastra Studio에서 프로젝트를 열어 내보낸 데이터를 검사하세요.

• MASTRA_PROJECT_ID에 설정한 프로젝트를 열고 Open Studio를 선택합니다.
• Studio에서 Traces로 이동하여 Agent 및 Workflow Trace를 검사합니다.
• 필터 메뉴를 열고 Deployments → Service Name을 사용하여 특정 앱이나 배포의 Trace만 표시합니다.
• 프로젝트 대시보드의 Logs 페이지를 사용하여 내보낸 로그를 검사합니다. Mastra Studio로 배포할 때 Deployment → Service Name을 안정적인 값으로 설정하고 Observability 구성의 serviceName과 일치하도록 유지하세요. 여러 서비스나 배포가 동일한 프로젝트로 데이터를 전송할 때 Studio에서 Deployments → Service Name을 통해 Trace를 더 쉽게 필터링할 수 있습니다.

성능

정보

MastraPlatformExporter는 일괄 처리를 사용하여 네트워크 사용을 최적화합니다. 이벤트는 버퍼링되어 일괄적으로 전송되므로 오버헤드가 줄어들고 거의 실시간 가시성이 유지됩니다.

일괄 처리 동작

• 이벤트는 다음까지 일괄 처리됩니다.maxBatchSize (default: 1000).
• 배치가 가득 차거나 그 이후에 전송됩니다.maxBatchWaitMs (default: 5 seconds).
• 실패한 배치는 지수 백오프를 통해 재시도됩니다.
• Mastra Studio에 연결할 수 없는 경우 내보내기 Tool의 성능이 정상적으로 저하됩니다.

관련된

• 추적 개요
• MastraStorage수출업체