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

# 자동 측정항목 참조

Mastra는 추적된 실행에서 성능 및 사용량 측정항목을 자동으로 추출합니다. 이 페이지는 Mastra가 내보내는 모든 지표 이름, 레이블 및 컨텍스트 필드에 대한 완전한 참조입니다.

설정 지침은 다음을 참조하세요.[Metrics overview](https://mastra.zisheng.pro/ko/docs/observability/metrics/overview).

## Mastra가 자동 측정항목을 내보내는 경우

측정항목은 종료되면 범위에서 추출됩니다. 관측 가능성 계층은 완료된 각 범위를 검사하고 기간을 계산하며 (Model 생성 범위의 경우) 토큰 사용 데이터를 읽습니다. 수동 계측이 필요하지 않습니다.

### 측정항목 사용 가능 여부에 영향을 미치는 요소

다음과 같은 경우 측정항목이 저장소에 도달합니다.

1. `MastraStorageExporter`내보내기로 구성되었습니다.
2. 스토리지 백엔드는 측정항목(Observability 도메인이 활성화된 ClickHouse, DuckDB 또는 Postgres v-next)을 지원합니다.

측정항목을 사용할 수 없는 경우 다음을 참조하세요.[troubleshooting](#troubleshooting).

## 기간 측정항목

기간 메트릭은 span의 시작 및 종료 타임스탬프로 계산한 실행 시간을 밀리초 단위로 기록합니다. 각 기간 메트릭에는 span 상태에서 파생된 `ok` 또는 `error` 값의 `status` 레이블이 포함됩니다.

| 메트릭 이름                         | span 유형                                            | 설명                                              |
| ------------------------------ | -------------------------------------------------- | ----------------------------------------------- |
| `mastra_agent_duration_ms`     | `AGENT_RUN`                                        | Agent 실행 시간                                     |
| `mastra_tool_duration_ms`      | `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL` | MCP 및 Provider에서 실행된 Tool 호출을 포함한 Tool 호출 실행 시간 |
| `mastra_workflow_duration_ms`  | `WORKFLOW_RUN`                                     | Workflow 실행 시간                                  |
| `mastra_model_duration_ms`     | `MODEL_GENERATION`                                 | Model 생성 실행 시간                                  |
| `mastra_processor_duration_ms` | `PROCESSOR_RUN`                                    | 프로세서 실행 시간                                      |

## 토큰 사용 지표

토큰 메트릭은 `usage` 데이터를 포함하는 `MODEL_GENERATION` span에서만 내보냅니다. 토큰 메트릭에는 Provider의 사용량 데이터가 필요합니다.

### 입력 토큰 측정항목

| 메트릭 이름                                  | 설명                                |
| --------------------------------------- | --------------------------------- |
| `mastra_model_total_input_tokens`       | 총 입력 토큰 수                         |
| `mastra_model_input_text_tokens`        | 입력 Prompt의 텍스트 토큰 수               |
| `mastra_model_input_cache_read_tokens`  | Prompt 캐시에서 읽은 토큰 수(예: Anthropic) |
| `mastra_model_input_cache_write_tokens` | Prompt 캐시에 기록한 토큰 수               |
| `mastra_model_input_audio_tokens`       | 입력의 오디오 토큰 수(멀티모달 Model)          |
| `mastra_model_input_image_tokens`       | 입력의 이미지 토큰 수(비전 Model)            |

### 출력 토큰 측정항목

| 메트릭 이름                                 | 설명                                |
| -------------------------------------- | --------------------------------- |
| `mastra_model_total_output_tokens`     | 총 출력 토큰 수                         |
| `mastra_model_output_text_tokens`      | Model 출력의 텍스트 토큰 수                |
| `mastra_model_output_reasoning_tokens` | 추론/사고 과정 토큰 수(예: OpenAI o-series) |
| `mastra_model_output_audio_tokens`     | Model 출력의 오디오 토큰 수                |
| `mastra_model_output_image_tokens`     | 출력 이미지 토큰 수                       |

### 공급자가 보고한 세부 토큰 카테고리

세부 분석 메트릭(`total_input` 및 `total_output` 제외)은 Provider가 보고하는 경우에만 내보냅니다. 범주의 토큰 수가 0이면 해당 span의 메트릭을 건너뜁니다. Provider마다 보고하는 세부 수준이 다릅니다. 예를 들어 일부 Provider는 캐시 또는 오디오 토큰을 보고하지 않습니다.

## 비용 관련 컨텍스트

### 비용 컨텍스트가 첨부된 경우

공급자가 완료된 모든 Model 단계에 대해 유효한 비용을 보고하거나 내장된 가격 책정 레지스트리에 공급자와 Model에 대해 일치하는 항목이 있는 경우 비용 컨텍스트가 토큰 지표에 첨부됩니다. Mastra는 단계당 공급자 비용을 하나의 쿼리 합계로 합산합니다. 완료된 단계에 보고된 유효한 비용이 부족한 경우 Mastra는 부분 합계를 보고하는 대신 가격 책정 레지스트리를 사용합니다. 두 소스를 모두 사용할 수 없는 경우 비용 필드 없이 토큰 지표가 계속 방출됩니다.

호출자가 제공한 `costContext`는 Provider가 보고한 비용과 가격 레지스트리의 추정치보다 우선합니다. Provider가 보고한 총계는 `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, `costMetadata.reportedStepCount`를 사용해 총계에 포함된 출처, 범위 및 완료 단계 수를 식별합니다.

### 포함될 수 있는 비용 필드

| 필드              | 설명                                                          |
| --------------- | ----------------------------------------------------------- |
| `provider`      | Provider 이름(예: `openai`, `anthropic`)                       |
| `model`         | Model 식별자(예: `gpt-4o`, `claude-sonnet-4-20250514`)          |
| `estimatedCost` | 토큰 수와 가격 등급을 기반으로 추정한 비용 또는 Provider가 보고한 총계                |
| `costUnit`      | 통화 단위(예: `USD`)                                             |
| `costMetadata`  | 등급 정보, 오류 세부 정보, Provider가 보고한 비용의 출처 및 범위를 포함하는 추가 가격 컨텍스트 |

## 추적과의 상관관계

### 측정항목이 범위 및 추적 컨텍스트와 관련되는 방식

각 메트릭에는 메트릭을 생성한 span의 `CorrelationContext` 스냅샷이 포함됩니다. 이 컨텍스트는 메트릭 값과 함께 저장되며 메트릭을 정확한 span 및 Trace에 연결합니다. 상관 필드는 다음 범주를 사용합니다.

**추적 상관관계**

- `traceId`: 추적 식별자
- `spanId`: 스팬 식별자
- `tags`: 범위의 태그

**엔터티 계층 구조**

- `entityType`, `entityId`, `entityName`: 메트릭을 생성한 엔터티(예: Agent, Workflow)

- `parentEntityType`, `parentEntityId`, `parentEntityName`: 상위 엔터티

- `rootEntityType`, `rootEntityId`, `rootEntityName`: 호출 체인의 루트 엔터티 **신원**

- `userId`, `organizationId`, `resourceId`: 요청의 ID 컨텍스트

- `runId`, `sessionId`, `threadId`, `requestId`: 상관관계 ID **전개**

- `environment`: 배포 환경(예:`production`, `staging`)

- `source`: 소스 식별자

- `serviceName`: 관측 가능성 구성의 서비스 이름

- `experimentId`: 실험 식별자(해당하는 경우)

### 상관관계가 디버깅에 도움이 되는 이유

지표 대시보드에서 지연 시간이나 토큰 사용량의 급증을 발견하면 상관 관계 컨텍스트를 통해 지표를 생성한 추적을 직접 살펴볼 수 있습니다. 여기에서 개별 범위를 검사할 수 있습니다. 근본 원인은 느린 Tool 호출이나 큰 Prompt일 수 있습니다. 예상치 못한 오류일 수도 있습니다.

## 문제 해결

### 측정항목이 없습니다.

- **Observability가 구성되어 있습니다.**: `Mastra` 인스턴스에 하나 이상의 exporter가 포함된 `observability` 구성이 있습니다.
- **`MastraStorageExporter` 또는 `MastraPlatformExporter`가 있습니다.**: 다른 exporter(Datadog, Langfuse 등)는 Mastra에 메트릭을 표시하지 않습니다. 로컬 Studio 대시보드에는 `MastraStorageExporter`가 필요하고, Mastra 플랫폼에서 메트릭을 보려면 `MastraPlatformExporter`가 필요합니다.
- **저장소에서 메트릭을 지원합니다.**: 메트릭에는 분석 지원 저장소(Observability 도메인이 활성화된 ClickHouse, DuckDB 또는 Postgres v-next)가 필요합니다. 다른 행 기반 데이터베이스(LibSQL, MSSQL)와 문서 저장소(MongoDB)는 메트릭을 지원하지 않습니다.
- **샘플링이 0%가 아닙니다.**: 샘플링 확률이 `0`이거나 전략이 `never`이면 모든 span이 no-op이 되어 메트릭이 추출되지 않습니다.

### 기간 측정항목이 누락되었습니다.

- **span에 타임스탬프가 있습니다.**: 기간은 `startTime`과 `endTime`으로 계산합니다. 둘 중 하나라도 없으면 메트릭을 건너뜁니다.
- **span 유형이 메트릭에 매핑됩니다.**: `AGENT_RUN`, `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `WORKFLOW_RUN`, `MODEL_GENERATION`, `PROCESSOR_RUN` span만 기간 메트릭을 생성합니다.

### 토큰 측정항목이 누락되었습니다.

- **span이 Model 생성입니다.**: 토큰 메트릭은 `MODEL_GENERATION` span에서만 내보냅니다.
- **Provider가 사용량을 보고합니다.**: Model Provider는 응답에 `usage` 데이터를 포함해야 합니다. 토큰 메트릭을 내보내려면 사용량 데이터가 필요합니다.

## 관련된

- [측정항목 개요](https://mastra.zisheng.pro/ko/docs/observability/metrics/overview)
- [측정항목 쿼리](https://mastra.zisheng.pro/ko/docs/observability/metrics/querying)
- [스튜디오 Observability](https://mastra.zisheng.pro/ko/docs/studio/observability)