자동 측정항목 참조

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

설정 지침은 다음을 참조하세요.Metrics overview.

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

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

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

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

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

측정항목을 사용할 수 없는 경우 다음을 참조하세요.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 데이터를 포함해야 합니다. 토큰 메트릭을 내보내려면 사용량 데이터가 필요합니다.

관련된

• 측정항목 개요
• 측정항목 쿼리
• 스튜디오 Observability