측정항목 쿼리

Mastra는 동일한 5개의 OLAP 쿼리(getMetricAggregate, getMetricBreakdown, getMetricTimeSeries, getMetricPercentiles및 검색 도우미) 세 가지 표면, 즉 프로세스 내 저장소 접근자, 런타임 HTTP API 및mastra api metricCLI. 세 가지 모두 동일한 Zod 검증 입력 형태를 허용하므로 API를 다시 학습하지 않고도 일회성 CLI 조사에서 프로그래밍 방식 대시보드 Tool로 이동할 수 있습니다.

AI Agent의 경우:달리다npx mastra api metric aggregate '{"name":"mastra_agent_duration_ms","aggregation":"avg"}' 를 사용하면 임시 스크립트를 작성하지 않고 Agent의 평균 지연 시간을 직접 쿼리할 수 있습니다. 로컬 메트릭을 쿼리하려면 OLAP 쿼리를 지원하는 Observability 스토어가 구성된 Mastra 서버가 실행 중이어야 합니다. 다음 명령으로 로컬 서버를 시작하세요: npx mastra dev, 또는 다음을 사용하여 접근 가능한 서버의 기본 URL을 전달하세요: --url. Run npx mastra api metric aggregate --schema 후 다른 쿼리를 작성하세요. 다음 명령으로 Mastra의 Skill을 설치하세요: npx skills add mastra-ai/skills --skill mastra 에서 API CLI 검색, 대상 지정, 스키마, 인증 및 오류 처리에 관한 전체 지침을 확인하세요.

이것을 언제 사용하는가

• Studio와 함께 맞춤형 대시보드 또는 KPI 타일을 구축하세요.
• 토큰 비용이나 대기 시간이 임계값을 초과할 때 실행되는 예약된 경고를 실행합니다.
• Agent에게 자체 성과 지표를 읽고 채팅으로 설명하는 Tool을 제공하세요.
• 다음을 사용하여 터미널에서 일회성 조사를 실행하세요.mastra api metric ....

Observability 저장소 자체를 설정하려면 다음을 참조하세요.Metrics overview. 쿼리할 수 있는 메트릭 이름 목록은 다음을 참조하세요: Automatic metrics reference.

:::참고 메트릭 쿼리는 OLAP 지원 저장소(DuckDB 로컬, ClickHouse 프로덕션)가 필요한 Observability 도메인에서 제공됩니다. 보다Metrics overview 에서 설정 방법을 확인하세요. Observability 스토어가 구성되어 있지 않으면 getStore('observability') returns null. :::

표면

진행 중

Tool, 서버 경로 또는 Workflow 단계 내에서 Mastra 스토리지에서 관측 가능성 저장소를 가져옵니다.

src/mastra/tools/agent-latency-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const agentLatencyTool = createTool({
  id: 'agentLatency',
  description: 'Average agent latency over the last hour.',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const observability = await context.mastra!.getStorage()!.getStore('observability')
    if (!observability) {
      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
    }

    const result = await observability.getMetricAggregate({
      name: ['mastra_agent_duration_ms'],
      aggregation: 'avg',
      filters: {
        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
      },
    })

    return { averageMs: result.value }
  },
})

getStore('observability')보고null 구성된 백엔드가 OLAP 쿼리를 지원하지 않을 때입니다.

HTTP

그만큼mastra dev 서버와 배포된 모든 Mastra 런타임은 다음 경로에서 동일한 쿼리를 제공합니다: /api/observability/metrics/*. 집계, 분류, 시계열 및 백분위수 엔드포인트는 다음을 포함하는 JSON 본문을 받습니다: POST. Discovery endpoints use GET with query parameters.

curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
  -H "content-type: application/json" \
  -d '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}'

이용 가능한 노선:

• POST /api/observability/metrics/aggregate
• POST /api/observability/metrics/breakdown
• POST /api/observability/metrics/timeseries
• POST /api/observability/metrics/percentiles
• GET /api/observability/metrics(원시 행, 페이지 매김)
• GET /api/observability/discovery/metric-names
• GET /api/observability/discovery/metric-label-keys
• GET /api/observability/discovery/metric-label-values

그만큼@mastra/client-js SDK wraps the same routes as mastraClient.getMetricAggregate(...), getMetricBreakdown(...), and so on.

CLI

mastra api metric ...단일 JSON 인수를 사용하여 동일한 엔드포인트를 호출하므로 Agent 또는 셸 스크립트는 코드를 작성하지 않고도 측정항목을 가져올 수 있습니다.

mastra api metric aggregate \
  '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}' \
  --url http://localhost:4111

기본적으로 CLI 대상은 Mastra Observability을 호스팅합니다(https://observability.mastra.ai). Pass --url http://localhost:4111 to query a local mastra dev server. See mastra api metric aggregate 및 그 주변 항목에서 전체 명령 목록을 확인하세요.

쿼리

getMetricAggregate

KPI 카드의 구성 요소인 단일 스칼라를 반환합니다.

입력:

• name: 하나 이상의 측정항목 이름 배열입니다.
• aggregation: 다음 중 하나'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'.
• filters: 선택사항filter object.
• comparePeriod: 선택사항'previous_period' | 'previous_day' | 'previous_week' for period-over-period comparison.

응답:

• value, previousValue, changePercent.
• estimatedCost, costUnit, previousEstimatedCost, costChangePercent for token metrics.

src/mastra/tools/token-cost-tool.ts

const observability = await mastra.getStorage()!.getStore('observability')

const cost = await observability!.getMetricAggregate({
  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
  aggregation: 'sum',
  comparePeriod: 'previous_day',
})

console.log(cost.value, cost.estimatedCost, cost.costUnit, cost.changePercent)

getMetricBreakdown

하나 이상의 측정기준으로 행을 그룹화하고 상위 N개 테이블의 구성 요소인 각 그룹을 집계합니다(예: "Agent별 토큰").

입력:

• name: 측정항목 이름의 배열입니다.
• groupBy: 그룹화 기준이 되는 필드 배열(예:['entityName']).
• aggregation: 위와 같은 열거형입니다.
• limit: 서버측 Top-K 캡입니다. 높은 카디널리티에 필요groupBy.
• orderDirection: 'ASC' | 'DESC' (defaults to DESC).
• filters: 선택사항입니다.

응답:groups[], each with dimensions (record of group keys to values), value, and estimatedCost.

const byAgent = await observability!.getMetricBreakdown({
  name: ['mastra_model_total_input_tokens'],
  groupBy: ['entityName'],
  aggregation: 'sum',
  limit: 10,
  orderDirection: 'DESC',
})

getMetricTimeSeries

고정 간격으로 버킷 값을 작성하며 선 및 막대형 차트의 구성 요소입니다.

입력:

• name: 측정항목 이름의 배열입니다.
• interval: 다음 중 하나'1m' | '5m' | '15m' | '1h' | '1d'.
• aggregation: 같은 열거형입니다.
• groupBy: 선택사항입니다. 생략하면 여러 측정항목 이름이 하나의 계열로 합산됩니다. 메트릭당 하나의 호출을 사용하여 별도로 유지합니다.
• filters: 선택사항입니다.

응답:series[], each with name, costUnit, and points[] of { timestamp, value, estimatedCost }.

const inputTokens = await observability!.getMetricTimeSeries({
  name: ['mastra_model_total_input_tokens'],
  aggregation: 'sum',
  interval: '1h',
  filters: {
    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
  },
})

getMetricPercentiles

지연 시간 차트의 구성 요소인 시간별로 버킷화된 백분위수 값을 반환합니다.

입력:

• name: 단일 메트릭 이름(배열이 아닌 문자열)입니다.
• percentiles: 사이의 숫자 배열0 and 1, for example [0.5, 0.95, 0.99].
• interval: 다음과 같은 열거형getMetricTimeSeries.
• filters: 선택사항입니다.

응답:series[], each with percentile and points[] of { timestamp, value }.

const latency = await observability!.getMetricPercentiles({
  name: 'mastra_agent_duration_ms',
  percentiles: [0.5, 0.95],
  interval: '1h',
})

발견

이러한 엔드포인트를 사용하여 드롭다운을 채우거나 Agent에 필터링할 수 있는 값 메뉴를 제공합니다. 모든 검색 경로는 다음과 같습니다.GET and live under /api/observability/discovery/.

측정항목별(또한 다음과 같이 노출됩니다.mastra api metric subcommands):

방법	인수	경로 접미사	CLI
getMetricNames	{ prefix?, limit? }	metric-names	mastra api metric names
getMetricLabelKeys	{ metricName }	metric-label-keys	mastra api metric label-keys
getMetricLabelValues	{ metricName, labelKey, prefix?, limit? }	metric-label-values	mastra api metric label-values

추적 및 로그와 공유(HTTP 전용, 전용 CLI 하위 명령 없음):

방법	인수	경로 접미사
getEntityTypes	{}	entity-types
getEntityNames	{ entityType? }	entity-names
getServiceNames	{}	service-names
getEnvironments	{}	environments
getTags	{ entityType? }	tags

필터링

모든 쿼리는 동일하게 허용됩니다.filters object. The most useful fields:

• name: 특정 측정항목 이름으로 제한됩니다. (최상위name 는 집계/분류/시계열에 대해 이미 이 작업을 수행합니다. 다음을 사용하세요: filters.name 단일 쿼리에서 여러 메트릭을 조합하려는 경우입니다.)
• timestamp: { start, end, startExclusive, endExclusive }. Both bounds are optional. Omit end for "until now".
• provider, model, costUnit: For token and cost metrics.
• labels: 측정항목 라벨의 정확한 키-값 일치(예:{ status: 'error' } for duration metrics.
• 상관관계 필드:entityType, entityName, parentEntityName, rootEntityName, userId, organizationId, resourceId, runId, sessionId, threadId, requestId, executionSource, environment, serviceName, experimentId, tags.

같은filters shape works across all three surfaces:

// In-process
await observability!.getMetricAggregate({
  name: ['mastra_tool_duration_ms'],
  aggregation: 'avg',
  filters: { entityName: 'weatherTool', labels: { status: 'error' } },
})

# CLI
mastra api metric aggregate \
  '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}' \
  --url http://localhost:4111

# HTTP
curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
  -H "content-type: application/json" \
  -d '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}'

항상 시간 범위를 제공하세요.

filters.timestamp선택 사항이지만 프로덕션 저장소에 대해 실행되는 모든 쿼리에 대해 필수로 처리해야 합니다. Observability 테이블은 일반적으로 이벤트 시간을 기준으로 분할(TimescaleDB의 경우 청크)됩니다. 공급할 때timestamp.start (and ideally end), 백엔드는 범위와 겹치는 파티션만 선별할 수 있으며, 일반적으로 한두 개입니다. 시간 범위가 없으면 플래너가 모든 파티션을 스캔해야 합니다. 보존 기간이 1년이면 파티션이 수백 개의 세그먼트에 이를 수 있으며, 이는 Postgres 기반 스토어에서 OLAP 쿼리가 느려지는 가장 흔한 원인입니다.

임시 쿼리의 안전한 기본값은 지난 24시간입니다. 경고 및 대시보드는 실제 평가 기간과 일치해야 합니다.

await observability!.getMetricAggregate({
  name: ['mastra_agent_duration_ms'],
  aggregation: 'p95',
  filters: {
    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
  },
})

이 지침은 모든 백엔드(ClickHouse, Postgres v-next, DuckDB)에 적용되지만 누락된 각 시간 제한이 하나의 추가 파티션 스캔으로 직접 변환되는 Postgres v-next의 경우 가장 중요합니다.

예: 사용자 정의 KPI 타일 구축

다음 Tool은 지난 시간 동안의 입력 토큰 볼륨과 예상 비용을 반환합니다. Agent나 대시보드에서는 이를 다음과 같이 호출할 수 있습니다.structuredContent without re-implementing the query.

src/mastra/tools/token-kpi-tool.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const tokenKpiTool = createTool({
  id: 'tokenKpi',
  description: 'Returns input-token volume and estimated cost for the last hour.',
  inputSchema: z.object({}),
  outputSchema: z.object({
    inputTokens: z.number().nullable(),
    estimatedCost: z.number().nullable(),
    costUnit: z.string().nullable(),
    changePercent: z.number().nullable(),
  }),
  execute: async (_input, context) => {
    const observability = await context.mastra!.getStorage()!.getStore('observability')
    if (!observability) {
      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
    }

    const result = await observability.getMetricAggregate({
      name: ['mastra_model_total_input_tokens'],
      aggregation: 'sum',
      filters: {
        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
      },
      comparePeriod: 'previous_period',
    })

    return {
      inputTokens: result.value,
      estimatedCost: result.estimatedCost ?? null,
      costUnit: result.costUnit ?? null,
      changePercent: result.changePercent ?? null,
    }
  },
})

관련된

• 측정항목 개요
• 자동 측정항목 참조
• CLI:mastra api metric ...
• 스튜디오 Observability