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

# Observability 개요

Mastra의 관찰 시스템은 모든 Agent 실행, Workflow 단계, Tool 호출 및 Model 상호 작용에 대한 가시성을 제공합니다. Agent 동작은 Model 응답, Prompt, Tool, Memory 및 Workflow 상태에 따라 달라지므로 관찰 기능은 첫날부터 런타임 결정을 검사하는 데 도움이 됩니다. 이는 애플리케이션이 수행하는 작업과 이유를 이해하는 데 도움이 되는 상호 보완적인 신호를 캡처합니다.

- [**구성**](#configuration): 추적, 로그, 지표, 피드백에 대해 Observability을 한 번 구성합니다.
- [**저장**](#storage): 지속적인 추적, 로그, 지표 집계 및 피드백 쿼리를 위한 스토리지 백엔드를 선택합니다.
- [**트레이싱**](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview): 모든 작업을 범위의 계층적 타임라인으로 기록하고 입력, 출력, 토큰 사용 및 타이밍을 캡처합니다.
- [**벌채 반출**](https://mastra.zisheng.pro/ko/docs/observability/logging): 애플리케이션 및 Mastra 내부의 구조화된 로그 항목을 Observability 스토리지로 전달하고 자동으로 추적과 연관시킵니다.
- [**측정항목**](https://mastra.zisheng.pro/ko/docs/observability/metrics/overview): 추적 사용량 및 비용 데이터를 추출합니다. 추가 계측이 필요하지 않습니다.
- [**피드백**](https://mastra.zisheng.pro/ko/docs/observability/feedback): 트레이스 및 범위에 연결된 등급, 설명, 수정 사항 및 기타 검토 신호를 저장합니다.
- [**통합**](https://mastra.zisheng.pro/ko/docs/observability/integrations/overview): Studio, 호스팅 또는 외부 관찰 Workflow를 위한 내보내기, 브리지 및 스팬 프로세서를 선택합니다.

## 관측성을 사용해야 하는 경우

- 전체 결정 경로, Tool 호출, Model 응답을 검사하여 예상치 못한 Agent 동작을 디버깅합니다.
- Agent, Workflow, Tool 전반의 대기 시간을 모니터링하여 병목 현상을 식별합니다.
- 시간 경과에 따른 토큰 소비 및 예상 비용을 추적하여 지출을 통제하세요.
- 각 단계의 실행을 추적하여 Workflow 오류를 진단합니다.
- Prompt나 Model 변경 전후의 Agent 성과를 비교하세요.

## 조각들이 어떻게 조화를 이루는가

Trace는 기반이 되는 요소입니다. Observability를 구성하면 모든 Agent 실행, Workflow 실행, Tool 호출 및 Model 상호 작용이 [스팬](https://opentelemetry.io/docs/concepts/signals/traces/#spans)을 생성합니다. 스팬은 전체 요청 수명 주기를 계층적 타임라인으로 보여 주는 Trace로 구성됩니다. 측정항목은 추적에서 자동으로 파생됩니다. 범위가 종료되면 Mastra는 추가 코드 없이 기간, 토큰 수 및 비용 견적을 추출합니다. 이러한 지표는 대시보드를 강화합니다.[Studio](https://mastra.zisheng.pro/ko/docs/studio/observability).

로그는 Trace와 자동으로 연관됩니다. Trace 컨텍스트 내의 모든 `logger.info()`, `logger.warn()`, `logger.error()` 호출에는 현재 Trace 및 스팬 ID가 태그로 지정됩니다. 로그 항목에서 해당 로그를 생성한 Trace로 바로 이동할 수 있습니다. 피드백은 평점, 의견, 수정 사항과 같은 사람의 검토 신호를 기록합니다. 피드백은 추적 및 범위에 연결된 다음 측정항목에 사용되는 것과 동일한 관측 가능성 저장소로 쿼리될 수 있습니다.

이러한 신호는 추적 ID, 범위 ID, 엔터티 유형, 엔터티 이름과 같은 상관 관계 ID를 공유합니다. 이를 사용하여 측정항목 급증에서 추적, 로그 및 관련 피드백으로 이동할 수 있습니다.

## 빠른 시작

`@mastra/observability`와 Trace 및 측정항목을 지원하는 스토리지 백엔드를 설치하세요.

**npm**:

```bash
npm install @mastra/observability @mastra/libsql @mastra/duckdb
```

**pnpm**:

```bash
pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
```

**Yarn**:

```bash
yarn add @mastra/observability @mastra/libsql @mastra/duckdb
```

**Bun**:

```bash
bun add @mastra/observability @mastra/libsql @mastra/duckdb
```

그런 다음 Mastra 인스턴스에서 Observability을 구성합니다. 다음 예에서는 복합 스토리지를 사용하여 관측 가능성 데이터를 DuckDB(메트릭 집계 지원)로 라우팅하는 동시에 다른 모든 것을 LibSQL에 유지합니다.

```ts
import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    },
  }),
  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
        ],
        logging: {
          enabled: true,
          level: 'info',
        },
      },
    },
  }),
})
```

Trace, 로그 전달 및 측정항목을 활성화합니다. Mastra는 Langfuse, Datadog 및 모든 OpenTelemetry 호환 플랫폼과 같은 외부 Trace Provider도 지원합니다. 외부 Provider로 데이터를 보내면서 Mastra Studio 접근을 유지하려면 [Studio 접근 유지](#maintaining-studio-access)를 참조하세요.

## 구성

Observability은 Mastra 인스턴스에서 한 번 구성되며 추적, 로그 및 지표에 걸쳐 적용됩니다.

### 기본 구성

관측 가능성 구성에는 일반적으로 다음이 포함됩니다.

- `serviceName`: 내보낸 관측 가능성 데이터에 첨부된 서비스 식별자입니다.
- `exporters`: 추적, 로그 및 파생 측정항목에 대한 하나 이상의 대상입니다.
- `spanOutputProcessors`: 범위를 내보내기 전에 실행되는 변환입니다.
- `logging`: 관측 가능성 저장소에 대한 로그 전달 설정입니다.

대상 및 프로세서에 대해서는 다음을 참조하세요.[Integrations overview](https://mastra.zisheng.pro/ko/docs/observability/integrations/overview).

### Studio 액세스 유지

외부 내보내기를 추가하는 경우 Studio Observability에는 `MastraStorageExporter`를, 호스팅된 Mastra 플랫폼 Observability에는 `MastraPlatformExporter`를 함께 추가하세요. 다음 예시에서는 관측 가능성 구성만 보여줍니다. 저장소를 별도로 구성하십시오.

```ts
import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
import { ArizeExporter } from '@mastra/arize'

export const observability = new Observability({
  configs: {
    production: {
      serviceName: 'my-service',
      exporters: [
        new ArizeExporter({
          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
          apiKey: process.env.PHOENIX_API_KEY,
        }),
        new MastraStorageExporter(),
        new MastraPlatformExporter(),
      ],
    },
  },
})
```

### 서버리스 환경에서 플러시

서버리스 환경에서는 런타임이 일시 중지되거나 종료되기 전에 관측 가능성 내보내기를 플러시합니다.

```ts
await mastra.observability.flush()
```

서버리스 환경에서는 로컬 파일 스토리지 대신 외부 스토리지를 사용하세요. 스토리지 선택 및 라우팅에 대해서는 [스토리지](#storage)를 참조하세요.

### 다중 구성 설정

다양한 환경이나 요청 유형에 다양한 내보내기 또는 샘플링 동작이 필요한 경우 여러 구성을 사용하세요. 다음을 사용하여 런타임 시 활성 구성을 선택합니다.`configSelector`.

```ts
import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
const langfuseExporter = new LangfuseExporter()

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      development: {
        serviceName: 'my-service-dev',
        exporters: [storageExporter],
      },
      production: {
        serviceName: 'my-service-prod',
        exporters: [storageExporter, langfuseExporter],
      },
    },
    configSelector: () => process.env.NODE_ENV || 'development',
  }),
})
```

추적 샘플링은 다음을 참조하세요.[Tracing](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview).

## 저장

스토리지는 어떤 관측 가능성 신호가 지속되는지, 어떤 쿼리가 사용 가능한지, 측정항목 집계가 작동하는지 여부를 결정합니다. 기본 애플리케이션 스토어 대신 전용 Observability 스토어를 사용하세요.

### 신호 지원

스토리지 지원 범위는 신호와 워크로드에 따라 다릅니다. `MastraStorageExporter`는 Trace를 ClickHouse, PostgreSQL, MSSQL, MongoDB 및 LibSQL에 영구 저장할 수 있습니다. 측정항목에는 분석 지원 스토리지가 필요합니다.

- DuckDB: 로컬 테스트 및 개발에 권장됩니다.
- ClickHouse: 대용량 프로덕션 Observability에 권장됩니다.
- `PostgresStoreVNext`: Observability 도메인이 활성화된 경우 측정항목을 지원합니다. 전체 파티션 스캔을 방지하려면 항상 시간 범위를 제공하세요.
- Mastra 플랫폼: 백엔드를 직접 관리하지 않고 호스팅된 Observability를 사용하려면 `MastraPlatformExporter`를 사용하세요. 전체 Provider 목록과 지원되는 Trace 전략은 [Mastra Storage 내보내기](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)를 참조하세요. 기본 스토리지가 Observability를 지원하지 않거나 워크로드를 독립적으로 확장해야 하는 경우 복합 스토리지를 사용하여 `observability` 도메인을 별도로 라우팅하세요.

### 지역 발전

로컬 개발의 경우 다음을 사용하십시오.

- `LibSQLStore`기본 애플리케이션 스토리지용
- `DuckDBStore`에 대한`observability` domain
- `MastraStorageExporter`로컬 스튜디오 액세스용

### 프로덕션 배포

Observability 트래픽은 일반적으로 애플리케이션의 나머지 부분보다 쓰기가 더 많습니다. 생산 중:

- 자체 스토리지에 Observability를 유지하려면 `observability` 도메인에 ClickHouse와 함께 `MastraStorageExporter`를 사용하세요.
- 백엔드를 직접 관리하는 대신 호스팅된 Mastra 플랫폼 Observability를 사용하려면 `MastraPlatformExporter`를 사용하세요.
- Observability에 기본 애플리케이션 데이터와 다른 백엔드 또는 확장 정책이 필요하다면 복합 스토리지를 사용하세요. 백엔드 호환성 세부정보 및 내보내기 일괄 처리 동작은 다음을 참조하세요.[Mastra Storage exporter](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage).

## 마스트라 플랫폼

프로젝트 및 배포 전반의 호스팅된 Trace, 로그 및 측정항목에 대해서는 [Mastra 플랫폼의 Observability](https://mastra.zisheng.pro/ko/docs/mastra-platform/observability)를 참조하세요.

## 다음 단계

- [트레이싱](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [벌채 반출](https://mastra.zisheng.pro/ko/docs/observability/logging)
- [측정항목](https://mastra.zisheng.pro/ko/docs/observability/metrics/overview)
- [피드백](https://mastra.zisheng.pro/ko/docs/observability/feedback)
- [통합 개요](https://mastra.zisheng.pro/ko/docs/observability/integrations/overview)
- [마스트라 스튜디오](https://mastra.zisheng.pro/ko/docs/studio/observability)
- [자동 측정항목 참조](https://mastra.zisheng.pro/ko/reference/observability/metrics/automatic-metrics)
- [Mastra 플랫폼 가시성](https://mastra.zisheng.pro/ko/docs/mastra-platform/observability)