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

# 측정항목 개요

Mastra는 추적된 실행에서 성능 및 사용량 측정항목을 자동으로 내보냅니다. 수동 계측이 필요하지 않습니다. 측정항목은 완료되면 범위에서 파생됩니다.

다음 측정항목 카테고리가 자동으로 내보내집니다.

- **기간 측정항목**: Agent, Workflow, Tool, Model 호출 및 프로세서의 실행 시간입니다.
- **토큰 사용 지표**: 유형(텍스트, 캐시, 오디오, 이미지, 추론)별로 분류된 입력 및 출력 토큰 수입니다.
- **비용 추정**: 내장된 가격 책정 레지스트리를 기반으로 한 Model 호출당 예상 비용입니다.

> **노트:** 측정항목에는 Observability을 위한 분석 가능 저장소가 필요합니다. 대부분의 관계형 데이터베이스(LibSQL, MSSQL)는 메트릭에 지원되지 않습니다. 다시 시작하면 Memory 내 저장소가 재설정됩니다.
>
> 로컬 개발에는 `@mastra/duckdb`를 통해 [DuckDB](https://duckdb.org/)를 사용하세요. 프로덕션에는 `@mastra/clickhouse`를 통해 [ClickHouse](https://clickhouse.com/)를 사용하세요. Observability 도메인이 활성화된 `PostgresStoreVNext`도 측정항목을 지원하지만, 전체 파티션 스캔을 방지하려면 항상 시간 범위를 제공하세요. Google Cloud Spanner는 측정항목을 지원하지만 측정항목 워크로드가 많은 경우에는 권장되지 않습니다. 측정항목 워크로드는 쓰기 및 스캔 중심이므로 Spanner 어댑터는 기본적으로 측정항목을 비활성화합니다. 가벼운 워크로드에만 `disableMetrics: false`를 설정하거나 측정항목을 OLAP 스토리지로 라우팅하세요.

## 측정항목을 사용해야 하는 경우

- Agent, Tool, Workflow 및 Model 호출 전반에 걸쳐 대기 시간을 모니터링합니다.
- 시간 경과에 따른 토큰 소비 및 비용 추세 추적
- 성공률과 오류율을 비교하여 오류가 많은 Agent 또는 Tool을 식별합니다.
- Prompt, Model 또는 코드 변경 전후의 성능 비교

## 시작하기

필수 패키지를 설치합니다:

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

그런 다음 Observability 도메인을 DuckDB로 라우팅하는 복합 저장소를 사용하여 Observability을 구성합니다.

```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, 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()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

## 사진관

Studio 측정항목 대시보드는 KPI 카드, 세부 분석, 토큰 사용량 타임라인 및 구성 가능한 시간 범위를 통해 모든 자동 측정항목을 시각화합니다. 전체 안내는 [Studio Observability](https://mastra.zisheng.pro/ko/docs/studio/observability)를 참조하세요.

## Mastra가 측정하는 것

Mastra는 세 가지 범주의 지표를 자동으로 내보냅니다.

- **지속**: Agent, Workflow, Tool, Model 호출 및 프로세서의 실행 시간(밀리초)입니다.
- **토큰 사용**: 유형(텍스트, 캐시, 오디오, 이미지, 추론)별로 분류된 입력 및 출력 토큰 수입니다.
- **비용 추정**: 내장된 가격 책정 레지스트리를 기반으로 한 Model 호출당 예상 비용입니다.

각 지표는 추적 상관 관계 컨텍스트를 전달하므로 대시보드 급증부터 이를 유발한 정확한 범위까지 드릴링할 수 있습니다.

측정항목 이름, 라벨, 비용 필드의 전체 목록은 다음을 참조하세요.[Automatic metrics reference](https://mastra.zisheng.pro/ko/reference/observability/metrics/automatic-metrics).

## 자동 측정항목의 작동 방식

Mastra 자동 계측 Agent 실행, Workflow 단계, Tool 호출 및 Model 생성을 범위로 합니다. 범위가 종료되면 관측 가능성 계층은 범위에서 측정항목을 추출합니다.

1. **지속 시간**: 스팬의 시작 및 종료 타임스탬프에서 계산됩니다.
2. **토큰 사용량**: Model 생성 스팬의 `usage` 속성에서 추출됩니다.
3. **예상 비용**: Provider 및 Model 이름과 일치하는 내장 가격 레지스트리를 통해 각 토큰 측정항목을 계산합니다. 저장하기 전에 모든 측정항목 라벨은 알려진 높은 카디널리티 값(예: 추적 ID 및 UUID)을 차단하는 카디널리티 필터를 통과하여 저장 효율성을 유지합니다. 그런 다음 측정항목은 내부 이벤트 버퍼에 의해 일괄 처리되고`MastraStorageExporter`.

## 다음 단계

- [자동 측정항목 참조](https://mastra.zisheng.pro/ko/reference/observability/metrics/automatic-metrics)
- [측정항목 쿼리](https://mastra.zisheng.pro/ko/docs/observability/metrics/querying)
- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [스튜디오 Observability](https://mastra.zisheng.pro/ko/docs/studio/observability)
- [Observability 개요](https://mastra.zisheng.pro/ko/docs/observability/overview)
- [MastraStorageExporter 참조](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)