MCP Tools Reference: monitoring.googleapis.com

도구: list_metric_descriptors

Google Cloud 프로젝트에서 사용할 수 있는 측정항목 유형을 검색하는 기본 도구로 사용합니다. 모니터링하고 대시보드나 알림을 빌드하는 데 사용할 수 있는 데이터를 파악하는 첫 번째 단계로 적합합니다.

다음 코드 샘플은 curl를 사용하여 list_metric_descriptors MCP 도구를 호출하는 방법을 보여줍니다.

curl 요청
curl --location 'https://monitoring.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_metric_descriptors",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

ListMetricDescriptors 요청입니다.

ListMetricDescriptorsRequest

JSON 표현
{
  "name": string,
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "activeOnly": boolean
}
필드
name

string

필수 항목입니다. 요청을 실행할 프로젝트입니다. 형식은 다음과 같습니다.

projects/[PROJECT_ID_OR_NUMBER]
filter

string

선택사항입니다. 이 필드가 비어 있으면 모든 맞춤 및 시스템 정의 측정항목 설명자가 반환됩니다. 그렇지 않으면 filter에서 반환할 측정항목 설명자를 지정합니다. 예를 들어 다음 필터는 모든 맞춤 측정항목과 일치합니다.

metric.type = starts_with("custom.googleapis.com/")
pageSize

integer

선택사항입니다. 반환할 최대 결과 수인 양수입니다. 기본값과 최댓값은 10,000입니다. page_size가 0 이하 또는 10,000보다 큰 값이 제출되면 대신 최대 10,000개의 결과가 반환됩니다.

pageToken

string

선택사항입니다. 이 필드가 비어 있지 않으면 이 메서드에 대한 이전 호출에서 반환된 nextPageToken 값이 포함되어야 합니다. 이 필드를 사용하면 메서드가 이전 메서드 호출에서 추가 결과를 반환합니다.

activeOnly

boolean

선택사항입니다. true인 경우 최근 데이터 (약 25시간 이내)가 있는 측정항목 및 모니터링 리소스 유형만 응답에 포함됩니다. - 측정항목 설명자가 모니터링 리소스 유형을 열거하는 경우 측정항목 유형에 최근 데이터가 있는 모니터링 리소스 유형만 반환된 측정항목 설명자에 포함되며, 최근 데이터가 있는 모니터링 리소스 유형이 없으면 측정항목 설명자가 반환되지 않습니다. - 측정항목 설명자가 호환되는 모니터링 리소스 유형을 열거하지 않으면 측정항목 유형에 일부 모니터링 리소스 유형의 최신 데이터가 있는 경우에만 반환됩니다. 반환된 설명자는 모니터링 리소스 유형을 열거하지 않습니다.

출력 스키마

ListMetricDescriptors 응답입니다.

ListMetricDescriptorsResponse

JSON 표현
{
  "metricDescriptors": [
    {
      object (MetricDescriptor)
    }
  ],
  "nextPageToken": string
}
필드
metricDescriptors[]

object (MetricDescriptor)

프로젝트에서 사용할 수 있고 filter 값과 일치하는 측정항목 설명자입니다(있는 경우).

nextPageToken

string

반환된 결과보다 더 많은 결과가 있으면 이 필드가 비어 있지 않은 값으로 설정됩니다. 추가 결과를 보려면 이 값을 다음 메서드 호출에서 page_token로 사용하세요.

MetricDescriptor

JSON 표현
{
  "name": string,
  "type": string,
  "labels": [
    {
      object (LabelDescriptor)
    }
  ],
  "metricKind": enum (MetricKind),
  "valueType": enum (ValueType),
  "unit": string,
  "description": string,
  "displayName": string,
  "metadata": {
    object (MetricDescriptorMetadata)
  },
  "launchStage": enum (LaunchStage),
  "monitoredResourceTypes": [
    string
  ]
}
필드
name

string

측정항목 설명자의 리소스 이름입니다.

type

string

DNS 이름 접두사를 포함한 측정항목 유형입니다. 유형은 URL 인코딩되지 않습니다. 모든 사용자 정의 측정항목 유형에는 DNS 이름 custom.googleapis.com 또는 external.googleapis.com이 있습니다. 측정항목 유형은 자연스러운 계층적 그룹화를 사용해야 합니다. 예를 들면 다음과 같습니다.

"custom.googleapis.com/invoice/paid/amount"
"external.googleapis.com/prometheus/up"
"appengine.googleapis.com/http/server/response_latencies"
labels[]

object (LabelDescriptor)

이 측정항목 유형의 특정 인스턴스를 설명하는 데 사용할 수 있는 라벨 집합입니다. 예를 들어 appengine.googleapis.com/http/server/response_latencies 측정항목 유형에는 HTTP 응답 코드(response_code) 라벨이 있으므로 성공한 응답의 지연 시간이나 실패한 응답의 지연 시간만 확인할 수 있습니다.

metricKind

enum (MetricKind)

측정항목이 순간 값, 값의 변경사항 등을 기록하는지 여부입니다. metric_kind 및 value_type의 일부 조합은 지원되지 않을 수 있습니다.

valueType

enum (ValueType)

측정값이 정수인지, 부동 소수점 수인지 등을 나타냅니다. metric_kind 및 value_type의 일부 조합은 지원되지 않을 수 있습니다.

unit

string

측정항목 값이 보고되는 단위입니다. value_type이 INT64, DOUBLE 또는 DISTRIBUTION인 경우에만 적용됩니다. unit은 저장된 측정항목 값의 표현을 정의합니다.

시스템에 따라 값을 더 쉽게 표시할 수 있도록 조정할 수 있습니다 (예: 0.02kBy 값이 20By로 표시되고 3523kBy 값이 3.5MBy로 표시될 수 있음). 하지만 unit가 kBy인 경우 측정항목 값은 표시 방식과 관계없이 항상 바이트 단위로 표시됩니다.

작업에서 사용한 정확한 CPU 초 수를 기록하는 맞춤 측정항목을 원하는 경우 unit이 s{CPU} (또는 이와 동등한 1s{CPU} 또는 s)인 INT64 CUMULATIVE 측정항목을 만들면 됩니다. 작업에서 12,005 CPU 초를 사용하면 값이 12005로 기록됩니다.

또는 맞춤 측정항목이 더 세부적인 방식으로 데이터를 기록하도록 하려면 unit이 ks{CPU}인 DOUBLE CUMULATIVE 측정항목을 만든 다음 값 12.005 (12005/1000)을 작성하거나 Kis{CPU}을 사용하여 11.723 (12005/1024)을 작성하면 됩니다.

지원되는 단위는 측정 단위 통합 코드 표준의 하위 집합입니다.

기본 단위 (UNIT)

  • bit비트
  • By바이트
  • s초
  • min분
  • h시간
  • d일
  • 1 무차원

접두사 (PREFIX)

  • k 킬로 (10^3)
  • M 메가 (10^6)
  • G 기가 (10^9)
  • T 테라 (10^12)
  • P 페타 (10^15)
  • E 엑사 (10^18)
  • Z 제타 (10^21)
  • Y 요타 (10^24)
  • m 밀리 (10^-3)

  • u 마이크로 (10^-6)
  • n 나노 (10^-9)
  • p 피코 (10^-12)
  • f 펨토 (10^-15)
  • a 아토 (10^-18)
  • z zepto (10^-21)
  • y 욕토 (10^-24)
  • Ki 키비 (2^10)

  • Mi메비 (2^20)
  • Gi와 같은 (2^30)
  • Ti 테비 (2^40)
  • Pi pebi (2^50)

문법

문법에는 다음 커넥터도 포함됩니다.

  • / 나누기 또는 비율 (중위 연산자) 예를 들어 kBy/{email} 또는 MiBy/10ms입니다 (측정항목 unit에는 /s가 거의 없어야 함. 비율은 항상 기본 누적 값 또는 델타 값에서 쿼리 시간에 계산해야 함).
  • . 곱셈 또는 합성 (중위 연산자) 예를 들면 GBy.d 또는 k{watt}.h입니다.

단위의 문법은 다음과 같습니다.

Expression = Component { "." Component } { "/" Component } ;

Component = ( [ PREFIX ] UNIT | "%" ) [ Annotation ]
          | Annotation
          | "1"
          ;

Annotation = "{" NAME "}" ;

참고:

  • Annotation는 UNIT 다음에 오는 경우에만 주석입니다. 주석이 단독으로 사용되면 단위는 1와 동일합니다. 예를 들면 {request}/s == 1/s, By{transmitted}/s == By/s입니다.
  • NAME은 { 또는 }을 포함하지 않는 공백이 아닌 인쇄 가능한 ASCII 문자의 시퀀스입니다.
  • 1는 1/s와 같은 1의 단위 측정기준이 없는 단위를 나타냅니다. 일반적으로 기본 단위가 적절하지 않은 경우에 사용됩니다. 예를 들어 '일별 신규 사용자 수'는 1/d 또는 {new-users}/d로 나타낼 수 있으며 측정항목 값 5는 '신규 사용자 5명'을 의미합니다. 또는 '일일 페이지 조회수 수천'은 1000/d 또는 k1/d 또는 k{page_views}/d로 표시됩니다 (측정항목 값 5.3은 '일일 페이지 조회수 5,300'을 의미).
  • %는 무차원 값 1/100을 나타내며 백분율을 제공하는 값에 주석을 답니다. 따라서 측정항목 값은 일반적으로 0~100 범위에 있으며 측정항목 값 3는 '3%'를 의미합니다.
  • 10^2.%는 측정항목에 일반적으로 0~1 범위의 비율이 포함되어 있으며, 이 비율에 100을 곱하여 백분율로 표시됨을 나타냅니다 (따라서 측정항목 값 0.03는 '3%'를 의미함).
description

string

문서에 사용할 수 있는 측정항목에 대한 자세한 설명입니다.

displayName

string

사용자 인터페이스에 표시될 수 있는 측정항목의 간결한 이름입니다. 마침표 없이 첫 글자를 대문자로 표기합니다(예: '요청 수'). 이 필드는 선택사항이지만 할당량과 같이 사용자에게 표시되는 개념과 연결된 측정항목에 설정하는 것이 좋습니다.

metadata

object (MetricDescriptorMetadata)

선택사항입니다. 측정항목의 사용을 안내하는 데 사용할 수 있는 메타데이터입니다.

launchStage

enum (LaunchStage)

선택사항입니다. 측정항목 정의의 출시 단계입니다.

monitoredResourceTypes[]

string

읽기 전용입니다. 있는 경우 측정항목 유형과 이 측정항목 유형과 연결된 MonitoredResourceDescriptor으로 부분적으로 식별되는 time series은 여기에 나열된 모니터링 리소스 유형 중 하나와만 연결될 수 있습니다.

LabelDescriptor

JSON 표현
{
  "key": string,
  "valueType": enum (ValueType),
  "description": string
}
필드
key

string

이 라벨의 키입니다. 키는 다음 기준을 충족해야 합니다.

  • 100자(영문 기준)를 초과하지 않습니다.
  • 다음 정규 표현식과 일치합니다. [a-zA-Z][a-zA-Z0-9_]*
    • 첫 번째 문자는 대문자 또는 소문자여야 합니다.
    • 나머지 문자는 문자, 숫자 또는 밑줄이어야 합니다.
valueType

enum (ValueType)

라벨에 할당할 수 있는 데이터 유형입니다.

description

string

라벨에 대한 사람이 읽을 수 있는 설명입니다.

MetricDescriptorMetadata

JSON 표현
{
  "launchStage": enum (LaunchStage),
  "samplePeriod": string,
  "ingestDelay": string,
  "timeSeriesResourceHierarchyLevel": [
    enum (TimeSeriesResourceHierarchyLevel)
  ]
}
필드
launchStage
(deprecated)

enum (LaunchStage)

지원 중단되었습니다. MetricDescriptor.launch_stage를 대신 사용해야 합니다.

samplePeriod

string (Duration format)

측정항목 데이터 포인트의 샘플링 기간입니다. 주기적으로 작성된 측정항목의 경우 연속된 데이터 포인트가 이 시간 간격으로 저장되며 오류로 인한 데이터 손실은 제외됩니다. 세분성이 높은 측정항목은 샘플링 기간이 더 짧습니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

ingestDelay

string (Duration format)

수집으로 인해 데이터 포인트가 지연됩니다. 이 기간보다 오래된 데이터 포인트는 오류로 인한 데이터 손실을 제외하고 수집되어 읽을 수 있습니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

timeSeriesResourceHierarchyLevel[]

enum (TimeSeriesResourceHierarchyLevel)

측정항목의 시계열 데이터 범위입니다.

소요 시간

JSON 표현
{
  "seconds": string,
  "nanos": integer
}
필드
seconds

string (int64 format)

시간 범위의 부호가 있는 초입니다. -315,576,000,000~+315,576,000,000(포함) 사이여야 합니다. 참고: 이 범위는 60초/분 * 60분/시간 * 24시간/일 * 365.25일/년 * 10,000년에서 계산됩니다.

nanos

integer

시간 범위의 나노초 단위로 된 부호가 있는 초수입니다. 1초 미만의 기간은 0 seconds 필드와 양수 또는 음수 nanos 필드로 표현됩니다. 1초 이상의 기간의 경우 nanos 필드의 0이 아닌 값은 seconds 필드와 부호가 같아야 합니다. -999,999,999~+999,999,999(포함) 사이여야 합니다.

ValueType

라벨 값으로 사용할 수 있는 값 유형입니다.

열거형
STRING 1,024자를 초과하지 않는 가변 길이 문자열 기본값 유형입니다.
BOOL 불리언(true 또는 false)
INT64 부호 있는 64비트 정수입니다.

MetricKind

측정 종류입니다. 데이터가 보고되는 방식을 설명합니다. MetricKind에 따라 시작 시간과 종료 시간을 설정하는 방법은 TimeInterval을 참조하세요.

열거형
METRIC_KIND_UNSPECIFIED 이 기본값을 사용하지 마세요.
GAUGE 값을 순간적으로 측정한 결과를 나타냅니다.
DELTA 특정 시간 간격 동안의 값의 변화량을 나타냅니다.
CUMULATIVE 특정 시간 간격 동안 누적된 값입니다. 시계열에서 누적 측정값은 동일한 시작 시간을 유지하고, 종료 시간은 증가해야 합니다. 누적 값이 0으로 재설정되는 이벤트가 발생하면, 그 이후 측정값부터는 새로운 시작 시간을 사용해야 합니다.

ValueType

측정항목의 값 유형입니다.

열거형
VALUE_TYPE_UNSPECIFIED 이 기본값을 사용하지 마세요.
BOOL 값이 불리언입니다. 이 값 유형은 측정항목 종류가 GAUGE인 경우에만 사용할 수 있습니다.
INT64 값이 부호 있는 64비트 정수입니다.
DOUBLE 값이 배정밀도 부동 소수점 수입니다.
STRING 값이 텍스트 문자열입니다. 이 값 유형은 측정항목 종류가 GAUGE인 경우에만 사용할 수 있습니다.
DISTRIBUTION 값이 Distribution입니다.
MONEY 값이 금액입니다.

LaunchStage

Google Cloud Platform 출시 단계에 정의된 출시 단계입니다.

열거형
LAUNCH_STAGE_UNSPECIFIED 이 기본값을 사용하지 마세요.
UNIMPLEMENTED 이 기능은 아직 구현되지 않았습니다. 사용자는 이 기능을 사용할 수 없습니다.
PRELAUNCH 사전 출시 기능은 사용자에게 표시되지 않으며 내부적으로만 표시됩니다.
EARLY_ACCESS 사전 체험판 기능은 특정 테스터 그룹에만 제한적으로 제공됩니다. 이 기능을 사용하려면 사전에 가입하고 기밀 유지 조항이 포함된 신뢰할 수 있는 테스터 계약에 서명해야 합니다. 이러한 기능은 안정적이지 않을 수 있고 이전 버전과 호환되지 않는 방식으로 변경될 수 있으며 정식 버전으로 출시되지 않을 수 있습니다.
ALPHA 알파는 더 널리 사용되도록 출시가 결정되기 전에 한정된 라이선스 인원으로 진행하는 테스트입니다. 알파 단계에서는 모든 중요한 설계 문제가 해결되고 기능 확인이 진행됩니다. 알파 고객은 액세스를 신청하고, 관련 약관에 동의하고, 프로젝트를 허용 목록에 추가해야 합니다. 알파 출시 버전은 기능이 완성되지 않은 상태일 수 있으며, SLA가 제공되지 않고, 기술 지원 의무도 없지만, 고객이 일반적인 프로덕션 사례에서와 마찬가지로 테스트 환경이나 제한된 사용 테스트에서 실제로 사용할 수 있을 만큼 충분히 진행됩니다.
BETA 베타는 모든 고객이 사용할 수 있도록 릴리스를 공개할 준비가 된 시점입니다. 베타 출시 버전에는 SLA 또는 기술 지원 의무가 없습니다. 제품은 기능 면에서는 완성된 상태이지만 몇 가지 미해결 문제가 있을 수 있습니다. 베타 버전은 제한된 프로덕션 사용 사례에 적합합니다.
GA GA 기능은 모든 개발자가 사용할 수 있으며 안정적이고 프로덕션 용도로 완전히 정규화된 것으로 간주됩니다.
DEPRECATED 지원 중단된 기능은 서비스 종료 및 폐기가 예정된 기능입니다. 자세한 내용은 서비스 약관의 '지원 중단 정책' 섹션 및 지원 중단 정책이 적용되는 Google Cloud Platform 문서를 참고하세요.

TimeSeriesResourceHierarchyLevel

측정항목의 시계열 데이터의 리소스 계층 구조 수준입니다.

열거형
TIME_SERIES_RESOURCE_HIERARCHY_LEVEL_UNSPECIFIED 이 기본값을 사용하지 마세요.
PROJECT 측정항목의 범위를 프로젝트로 지정합니다.
ORGANIZATION 측정항목을 조직으로 범위 지정합니다.
FOLDER 측정항목의 범위를 폴더로 지정합니다.

도구 주석

파괴적 힌트: ❌ | 멱등성 힌트: ✅ | 읽기 전용 힌트: ✅ | 오픈 월드 힌트: ❌