> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 트레이싱

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

:::warning\[업그레이드 시 Observability 데이터 흐름이 중지됨] `telemetry:` 구성을 `observability:`로 마이그레이션하지 않고 Mastra 패키지를 v1로 업그레이드하면 런타임에서 이전 구성이 무시됩니다. 서비스는 오류 없이 정상적으로 시작되지만 **Trace, 로그 또는 메트릭이 어디에도 전송되지 않습니다.** Mastra Cloud로 데이터를 전송하는 경우 대시보드가 비어 있게 됩니다. Mastra 패키지 변경과 함께 이 마이그레이션을 완료하고 [Mastra Studio](https://mastra.zisheng.pro/ko/docs/studio/observability)에 Trace가 표시되는지 확인한 후에 업그레이드가 완료된 것으로 간주하세요. 이전에 Mastra Cloud에서 호스팅했다면 [Mastra Cloud 마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/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):**

```typescript
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):**

```typescript
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 문서](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)를 참조하세요.

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

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

```typescript
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 문서](https://mastra.zisheng.pro/ko/docs/observability/integrations/overview)를 참조하세요.

### AI 추적에서

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

**이전(AI 추적):**

```typescript
import { Mastra } from '@mastra/core'

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

**이후(v1 Observability):**

```typescript
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**:

```bash
npm install @mastra/observability@latest
```

**pnpm**:

```bash
pnpm add @mastra/observability@latest
```

**Yarn**:

```bash
yarn add @mastra/observability@latest
```

**Bun**:

```bash
bun add @mastra/observability@latest
```

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

### 레지스트리 구성

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

```diff
+ 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`로 변경되었습니다. 마이그레이션하려면 구성 개체의 속성 이름을 바꾸세요.

```diff
+ 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`로 변경되었습니다. 마이그레이션하려면 사용자 정의 내보내기에서 메서드 구현을 업데이트하세요.

```diff
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](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview).

### 사용자 정의 계측 파일

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

### `instrumentation.mjs`파일

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

#### 이전(0.x)

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

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

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

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

#### 이후(v1)

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

```typescript
// 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:

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

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

## 공급자 마이그레이션 참조

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

| 공급자                                                       | 수출                | 가이드                                                                                         | 참고자료                                                                                            |
| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 아리즈 AX, 아리즈 피닉스                                           | **Arize**         | [Guide](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/arize)      | [Reference](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/arize)      |
| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/braintrust) | [Reference](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/braintrust) |
| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/langfuse)   | [Reference](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/langfuse)   |
| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/langsmith)  | [Reference](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/langsmith)  |
| Dash0, Laminar, New Relic, SigNoz, Traceloop, 사용자 지정 OTEL | **OpenTelemetry** | [Guide](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/otel)       | [Reference](https://mastra.zisheng.pro/ko/reference/observability/tracing/exporters/otel)       |
| LangWatch                                                 | \<coming soon>    | -                                                                                           | -                                                                                               |

### 설치

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

**npm**:

```bash
npm install @mastra/otel-exporter@latest
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest
```

또한 Provider에 필요한 프로토콜 패키지(참조:[OTEL guide](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/otel)).