> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # Mastra 플랫폼 수출업체 그만큼`MastraPlatformExporter`추적, 로그, 메트릭, 점수 및 피드백을 Mastra 플랫폼으로 보냅니다. 이를 사용하여 Mastra 앱의 관측 가능성 데이터를 Mastra 플랫폼의 호스팅 프로젝트로 라우팅합니다. > **노트:** `MastraPlatformExporter`는 이전에 `CloudExporter`라고 불렸습니다. 원래 `CloudExporter` 클래스는 이전 버전과의 호환성을 위해 여전히 `@mastra/observability`에서 내보내지만 더 이상 사용되지 않습니다. 새 코드에서는 `MastraPlatformExporter`를 사용해야 합니다. :::note\[자체 호스팅 또는 독립형 앱] Mastra 플랫폼이 아닌 자체 인프라에서 Mastra 애플리케이션을 호스팅하는 경우에도 Trace, 로그 및 측정항목을 보려면 배포된 Studio 프로젝트가 필요합니다. `MastraPlatformExporter`는 데이터를 Studio 프로젝트로 전송하므로 사용 전에 프로젝트가 존재해야 합니다. 1. 아직 없다면 [Mastra 프로젝트를 만드세요](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart). 2. `mastra studio deploy`를 사용해 [Studio를 Mastra 플랫폼에 배포하세요](https://mastra.zisheng.pro/ko/docs/studio/deployment). 3. 액세스 토큰을 만들고 프로젝트 ID를 찾으려면 [아래의 빠른 시작 단계](#quickstart)를 따르세요. ::: ## 버전 호환성 - `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. 액세스 토큰 생성 다음 명령을 실행하십시오. ```bash mastra auth tokens create exporter-token ``` 이 명령은 다음과 같이 사용할 수 있는 토큰 비밀을 인쇄합니다.`MASTRA_PLATFORM_ACCESS_TOKEN`. 이미 액세스 토큰이 있다면 Mastra 플랫폼의 **Observability** 값을 대신 사용하세요. 다음 위치 중 하나에서 찾을 수 있습니다. - **Projects** 페이지에서 프로젝트 목록을 열고 프로젝트 카드의 **Observability** 행을 찾습니다. - 프로젝트의 **Overview** 페이지에서 배포 URL 바로 아래에 있는 **Observability** 행을 찾습니다. 토큰을 환경 변수로 설정합니다. ```bash MASTRA_PLATFORM_ACCESS_TOKEN= ``` ### 2. 당신의 것을 찾으세요`projectId` 다음 명령을 실행하십시오. ```bash mastra studio deploy list ``` 출력은 다음과 유사합니다. ```text ✅ () Latest: 00000000-0000-0000-0000-000000000000 — running URL: https://260407.studio.mastra.cloud ``` 이 출력에서 ​​괄호 안의 값은`projectId`: ```text ``` 환경 변수로 설정하십시오. ```bash MASTRA_PROJECT_ID= ``` ### 3. 환경 변수 설정 `MastraPlatformExporter`가 인증하고 원격 분석을 올바른 프로젝트로 라우팅할 수 있도록 환경에 두 값을 모두 설정하세요. ```bash MASTRA_PLATFORM_ACCESS_TOKEN= MASTRA_PROJECT_ID= ``` `@mastra/observability@1.8.0`부터 `1.9.1`까지를 사용하는 경우 Mastra 플랫폼 수집기도 명시적으로 설정하세요. ```bash MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai ``` Mastra 플랫폼 이외의 위치로 원격 분석을 보내려면 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`도 설정하세요. 기본 오리진 또는 `/spans/publish`로 끝나는 전체 Trace 게시 URL을 전달할 수 있습니다. ```bash MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com ``` 기본 오리진을 전달하면 `MastraPlatformExporter`가 Trace, 로그, 측정항목, 점수 및 피드백에 맞는 게시 URL을 자동으로 파생합니다. ### 4. 활성화`MastraPlatformExporter` 다음 예제에서는 Observability 구성에 `MastraPlatformExporter`를 추가하는 방법을 보여 줍니다. ```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 구성 레퍼런스](https://mastra.zisheng.pro/ko/reference/observability/tracing/configuration)를 참조하세요. 원한다면 전적으로 환경 변수에 의존하세요. ```ts new MastraPlatformExporter() ``` `MASTRA_PLATFORM_ACCESS_TOKEN`과 `MASTRA_PROJECT_ID`를 설정하면 `MastraPlatformExporter`가 구성한 Mastra 플랫폼 프로젝트로 데이터를 전송합니다. `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`도 설정하면 대신 해당 수집기로 데이터를 전송합니다. 전체 구성 옵션 목록은 [MastraPlatformExporter 레퍼런스](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/mastra-platform-exporter)를 참조하세요. ## 권장 구성 Studio에서 로컬 Trace도 검사하거나 Observability 데이터를 구성된 스토리지에 영구 저장하려면 `MastraStorageExporter`를 포함하세요. ```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`를 전달하세요. ```bash MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com ``` 다음 예에서는 코드에서 수집기 끝점 및 일괄 처리 동작을 재정의하는 방법을 보여줍니다. ```ts new MastraPlatformExporter({ endpoint: 'https://collector.example.com', maxBatchSize: 1000, maxBatchWaitMs: 5000, logLevel: 'info', }) ``` ## Mastra Studio에서 데이터 보기 `MastraPlatformExporter`를 활성화한 후 [Mastra Studio](https://projects.mastra.ai)에서 프로젝트를 열어 내보낸 데이터를 검사하세요. - `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의 성능이 정상적으로 저하됩니다. ## 관련된 - [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview) - [MastraStorage수출업체](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)