트레이싱

관측 가능성 시스템은 v1에서 전용으로 재구성되었습니다.@mastra/observability패키지. 이 가이드에서는 업그레이드하려는 버전에 따라 두 가지 마이그레이션 경로를 다룹니다.

:::warning[업그레이드 시 Observability 데이터 흐름이 중지됨] telemetry: 구성을 observability:로 마이그레이션하지 않고 Mastra 패키지를 v1로 업그레이드하면 런타임에서 이전 구성이 무시됩니다. 서비스는 오류 없이 정상적으로 시작되지만 Trace, 로그 또는 메트릭이 어디에도 전송되지 않습니다. Mastra Cloud로 데이터를 전송하는 경우 대시보드가 비어 있게 됩니다. Mastra 패키지 변경과 함께 이 마이그레이션을 완료하고 Mastra Studio에 Trace가 표시되는지 확인한 후에 업그레이드가 완료된 것으로 간주하세요. 이전에 Mastra Cloud에서 호스팅했다면 Mastra Cloud 마이그레이션 가이드도 따르세요. 새 플랫폼에서 MastraPlatformExporter가 데이터를 라우팅하려면 새로운 액세스 토큰과 Studio 프로젝트가 필요합니다. ::: :::note[내보내기 이름 변경]

MastraPlatformExporter(Mastra 플랫폼으로 데이터 전송)는 이전 CloudExporter를 대체하고, MastraStorageExporter(Mastra Storage에 데이터 유지)는 이전 DefaultExporter를 대체합니다. 기존 클래스는 @mastra/observability에서 계속 사용할 수 있고 동일하게 작동하지만 더 이상 사용하지 않는 것이 권장됩니다. 새 코드에서는 MastraPlatformExporter와 MastraStorageExporter를 사용해야 합니다. 기존 CloudExporter 또는 DefaultExporter 가져오기는 향후 메이저 버전에서 제거될 때까지 계속 작동합니다. :::

마이그레이션 경로

OTEL 기반 원격 측정(0.x)에서

Mastra에서 이전 telemetry: 구성을 사용하고 있다면 시스템이 완전히 새롭게 설계되었다는 점에 유의하세요. 이전(OTEL 원격 측정을 사용하는 0.x):

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  telemetry: {
    serviceName: 'my-app',
    enabled: true,
    sampling: {
      type: 'always_on',
    },
    export: {
      type: 'otlp',
      endpoint: 'http://localhost:4318',
    },
  },
})

이후(관측 가능성이 있는 v1):

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(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})

이 구성에는 MastraStorageExporter, MastraPlatformExporter 및 SensitiveDataFilter 프로세서가 포함됩니다. 전체 구성 옵션은 Observability Trace 문서를 참조하세요.

이후(맞춤 구성이 포함된 v1)

특정 내보내기(예: OTLP)를 구성해야 하는 경우 내보내기 패키지를 설치하고 구성합니다.

npm

npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

pnpm

pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

Yarn

yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

Bun

bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'my-app',
        sampling: { type: 'always' },
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: 'http://localhost:4318/v1/traces',
                protocol: 'http/protobuf',
              },
            },
          }),
        ],
      },
    },
  }),
})

주요 변경 사항:

1. @mastra/observability 패키지 설치
2. telemetry:를 observability: new Observability()로 변경
3. MastraStorageExporter, MastraPlatformExporter 및 SensitiveDataFilter와 함께 명시적인 configs: 사용
4. 내보내기 타입이 문자열 리터럴('otlp')에서 Exporter 클래스 인스턴스(new OtelExporter())로 변경됨 사용 가능한 모든 Exporter는 Exporter 문서를 참조하세요.

AI 추적에서

이미 AI 추적(중간 시스템)으로 업그레이드한 경우 새 패키지를 설치하고 명시적 구성을 사용해야 합니다.

이전(AI 추적):

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  observability: {
    default: { enabled: true },
  },
})

이후(v1 Observability):

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()],
      },
    },
  }),
})

주요 변경 사항:

1. @mastra/observability 패키지 설치
2. @mastra/observability에서 Observability, Exporter 및 프로세서 가져오기
3. MastraStorageExporter, MastraPlatformExporter 및 SensitiveDataFilter와 함께 명시적인 configs 사용

변경됨

패키지 가져오기 경로

Observability 기능이 전용으로 이동되었습니다.@mastra/observability package.

마이그레이션하려면 패키지를 설치하고 가져오기 문을 업데이트하세요.

npm

npm install @mastra/observability@latest

pnpm

pnpm add @mastra/observability@latest

Yarn

yarn add @mastra/observability@latest

Bun

bun add @mastra/observability@latest

- import { Tracing } from '@mastra/core/observability';
+ import { Observability } from '@mastra/observability';

레지스트리 구성

이제 Observability 레지스트리는 일반 객체 대신 명시적인 구성을 포함한 Observability 클래스 인스턴스를 사용하여 구성합니다. 마이그레이션하려면 명시적인 Exporter 및 프로세서와 함께 new Observability()를 사용하세요.

+ import {
+   Observability,
+   MastraStorageExporter,
+   MastraPlatformExporter,
+   SensitiveDataFilter,
+ } from '@mastra/observability';

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

구성 속성 processors에서 spanOutputProcessors로

스팬 프로세서의 구성 속성 이름이 processors에서 spanOutputProcessors로 변경되었습니다. 마이그레이션하려면 구성 개체의 속성 이름을 바꾸세요.

+ import { SensitiveDataFilter } from '@mastra/observability';

  export const mastra = new Mastra({
    observability: new Observability({
      configs: {
        production: {
          serviceName: 'my-app',
-         processors: [new SensitiveDataFilter()],
+         spanOutputProcessors: [new SensitiveDataFilter()],
          exporters: [...],
        },
      },
    }),
  });

Exporter 메서드 exportEvent에서 exportTracingEvent로

사용자 지정 Exporter를 만든 경우 내보내기 메서드의 이름이 exportEvent에서 exportTracingEvent로 변경되었습니다. 마이그레이션하려면 사용자 정의 내보내기에서 메서드 구현을 업데이트하세요.

  export class MyExporter implements ObservabilityExporter {
-   exportEvent(event: TracingEvent): void {
+   exportTracingEvent(event: TracingEvent): void {
      // export logic
    }
  }

제거됨

OTEL 기반telemetry configuration

0.x의 OTEL 기반 telemetry 구성이 제거되었습니다. serviceName, sampling.type 및 export.type 속성을 사용하는 이전 시스템은 더 이상 지원되지 않습니다. 마이그레이션하려면 위의 "OTEL 기반 원격 측정에서" 섹션을 따르세요. 자세한 구성 옵션은 다음을 참조하세요.observability tracing documentation.

사용자 정의 계측 파일

/mastra에서 계측 파일(.ts, .js 또는 .mjs 확장자)을 자동 감지하는 기능이 제거되었습니다. 별도의 파일을 통한 사용자 지정 계측은 더 이상 지원되지 않습니다. 마이그레이션하려면 내장 Exporter 시스템 또는 ObservabilityExporter 인터페이스를 사용하세요. 자세한 내용은 Exporter 문서를 참조하세요.

instrumentation.mjs파일

OpenTelemetry 계측을 초기화하기 위해 instrumentation.mjs 파일을 사용했다면(AWS Lambda 같은 배포 설정에서 일반적), 이제 이 파일은 필요하지 않습니다. 새로운 Observability 시스템은 Mastra 인스턴스에서 직접 구성합니다.

이전(0.x)

계측 파일이 필요했습니다.

// instrumentation.mjs
import { NodeSDK } from '@opentelemetry/sdk-node'
// ... OTEL setup

프로세스를 시작할 때 이를 가져와야 했습니다.

node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs

이후(v1)

instrumentation.mjs 파일을 제거하고 Mastra 인스턴스에서 Observability를 구성하기만 하면 됩니다.

// src/mastra/index.ts
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()],
      },
    },
  }),
})

없이 프로세스를 정상적으로 시작하십시오.--import flag:

node --env-file=".env" .mastra/output/index.mjs

별도의 계측 파일이나 특수 시작 플래그가 필요하지 않습니다.

공급자 마이그레이션 참조

0.x에서 특정 공급자와 함께 OTEL 기반 원격 측정을 사용하는 경우 v1에서 구성하는 방법은 다음과 같습니다.

공급자	수출	가이드	참고자료
아리즈 AX, 아리즈 피닉스	Arize	Guide	Reference
Braintrust	Braintrust	Guide	Reference
Langfuse	Langfuse	Guide	Reference
LangSmith	LangSmith	Guide	Reference
Dash0, Laminar, New Relic, SigNoz, Traceloop, 사용자 지정 OTEL	OpenTelemetry	Guide	Reference
LangWatch	<coming soon>	-	-

설치

전용 수출업체(Arize, Braintrust, Langfuse, LangSmith):

npm

npm install @mastra/[exporter-name]-exporter

pnpm

pnpm add @mastra/[exporter-name]-exporter

Yarn

yarn add @mastra/[exporter-name]-exporter

Bun

bun add @mastra/[exporter-name]-exporter

OpenTelemetry 내보내기(Dash0, Laminar, New Relic, SigNoz, Traceloop):

npm

npm install @mastra/otel-exporter@latest

pnpm

pnpm add @mastra/otel-exporter@latest

Yarn

yarn add @mastra/otel-exporter@latest

Bun

bun add @mastra/otel-exporter@latest

또한 Provider에 필요한 프로토콜 패키지(참조:OTEL guide).