MCP Tools Reference: monitoring.googleapis.com

Strumento: list_metric_descriptors

Utilizza questo strumento principale per scoprire i tipi di metriche disponibili in un progetto Google Cloud. Questo è un buon primo passo per capire quali dati sono disponibili per il monitoraggio e la creazione di dashboard o avvisi.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP list_metric_descriptors.

Richiesta 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
}'

Schema di input

La richiesta ListMetricDescriptors.

ListMetricDescriptorsRequest

Rappresentazione JSON
{
  "name": string,
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "activeOnly": boolean
}
Campi
name

string

Obbligatorio. Il progetto su cui eseguire la richiesta. Il formato è:

projects/[PROJECT_ID_OR_NUMBER]
filter

string

Facoltativo. Se questo campo è vuoto, vengono restituiti tutti i descrittori di metriche personalizzati e definiti dal sistema. In caso contrario, il filtro specifica quali descrittori di metriche devono essere restituiti. Ad esempio, il seguente filtro corrisponde a tutte le metriche personalizzate:

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

integer

Facoltativo. Un numero positivo che rappresenta il numero massimo di risultati da restituire. Il valore predefinito e massimo è 10.000. Se viene inviato un valore page_size <= 0 o > 10.000, verranno restituiti al massimo 10.000 risultati.

pageToken

string

Facoltativo. Se questo campo non è vuoto, deve contenere il valore nextPageToken restituito da una chiamata precedente a questo metodo. L'utilizzo di questo campo fa sì che il metodo restituisca risultati aggiuntivi dalla chiamata al metodo precedente.

activeOnly

boolean

Facoltativo. Se è true, nella risposta verranno inclusi solo i tipi di metriche e risorsa monitorata che dispongono di dati recenti (entro circa 25 ore). Se un descrittore della metrica enumera i tipi di risorsa monitorata, nel descrittore della metrica restituito verranno inclusi solo i tipi di risorsa monitorata per i quali il tipo di metrica dispone di dati recenti e, se nessuno di questi dispone di dati recenti, il descrittore della metrica non verrà restituito. Se un descrittore della metrica non enumera i tipi di risorse monitorate compatibili, verrà restituito solo se il tipo di metrica dispone di dati recenti per un tipo di risorsa monitorata. Il descrittore restituito non elenca alcun tipo di risorsa monitorata.

Schema di output

La risposta ListMetricDescriptors.

ListMetricDescriptorsResponse

Rappresentazione JSON
{
  "metricDescriptors": [
    {
      object (MetricDescriptor)
    }
  ],
  "nextPageToken": string
}
Campi
metricDescriptors[]

object (MetricDescriptor)

I descrittori delle metriche disponibili per il progetto e che corrispondono al valore di filter, se presente.

nextPageToken

string

Se sono presenti più risultati di quelli restituiti, questo campo è impostato su un valore non vuoto. Per visualizzare i risultati aggiuntivi, utilizza questo valore come page_token nella chiamata successiva a questo metodo.

MetricDescriptor

Rappresentazione 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
  ]
}
Campi
name

string

Il nome della risorsa del descrittore della metrica.

type

string

Il tipo di metrica, incluso il prefisso del nome DNS. Il tipo non è codificato in formato URL. Tutti i tipi di metriche definite dall'utente hanno il nome DNS custom.googleapis.com o external.googleapis.com. I tipi di metrica devono utilizzare un raggruppamento gerarchico naturale. Ad esempio:

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

object (LabelDescriptor)

L'insieme di etichette che possono essere utilizzate per descrivere un'istanza specifica di questo tipo di metrica. Ad esempio, il tipo di metrica appengine.googleapis.com/http/server/response_latencies ha un'etichetta per il codice di risposta HTTP, response_code, in modo da poter esaminare le latenze per le risposte riuscite o solo per le risposte non riuscite.

metricKind

enum (MetricKind)

Indica se la metrica registra valori istantanei, modifiche a un valore e così via. Alcune combinazioni di metric_kind e value_type potrebbero non essere supportate.

valueType

enum (ValueType)

Indica se la misurazione è un numero intero, un numero in virgola mobile e così via. Alcune combinazioni di metric_kind e value_type potrebbero non essere supportate.

unit

string

Le unità in cui viene riportato il valore della metrica. È applicabile solo se value_type è INT64, DOUBLE o DISTRIBUTION. unit definisce la rappresentazione dei valori delle metriche memorizzati.

Sistemi diversi potrebbero scalare i valori per visualizzarli più facilmente (ad esempio, un valore di 0.02kBy potrebbe essere visualizzato come 20By e un valore di 3523kBy potrebbe essere visualizzato come 3.5MBy). Tuttavia, se unit è kBy, il valore della metrica è sempre in migliaia di byte, indipendentemente da come potrebbe essere visualizzato.

Se vuoi che una metrica personalizzata registri il numero esatto di secondi CPU utilizzati da un job, puoi creare una metrica INT64 CUMULATIVE il cui unit è s{CPU} (o equivalentemente 1s{CPU} o semplicemente s). Se il job utilizza 12.005 secondi CPU, il valore viene scritto come 12005.

In alternativa, se vuoi che una metrica personalizzata registri i dati in modo più granulare, puoi creare una metrica DOUBLE CUMULATIVE la cui unit è ks{CPU}, quindi scrivere il valore 12.005 (che è 12005/1000) o utilizzare Kis{CPU} e scrivere 11.723 (che è 12005/1024).

Le unità supportate sono un sottoinsieme dello standard The Unified Code for Units of Measure:

Unità di base (UNIT)

  • bit bit
  • By byte
  • s secondo
  • min minuto
  • h ora
  • d giorno
  • 1 senza unità di misura

Prefissi (PREFIX)

  • k chilo (10^3)
  • M mega (10^6)
  • G giga (10^9)
  • T tera (10^12)
  • P peta (10^15)
  • E exa (10^18)
  • Z zetta (10^21)
  • Y yotta (10^24)
  • m milli (10^-3)

  • u micro (10^-6)
  • n nano (10^-9)
  • p pico (10^-12)
  • f femto (10^-15)
  • a atto (10^-18)
  • z zepto (10^-21)
  • y yocto (10^-24)
  • Ki kibi (2^10)

  • Mi mebi (2^20)
  • Gi gibi (2^30)
  • Ti tebi (2^40)
  • Pi pebi (2^50)

Grammatica

La grammatica include anche i seguenti connettori:

  • / divisione o rapporto (come operatore infisso). Ad esempio, kBy/{email} o MiBy/10ms (anche se non dovresti quasi mai avere /s in una metrica unit; i tassi devono sempre essere calcolati al momento della query dal valore cumulativo o delta sottostante).
  • . moltiplicazione o composizione (come operatore infisso). Ad esempio, GBy.d o k{watt}.h.

La grammatica di un'unità è la seguente:

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

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

Annotation = "{" NAME "}" ;

Note:

  • Annotation è solo un commento se segue un UNIT. Se l'annotazione viene utilizzata da sola, l'unità equivale a 1. Ad esempio, {request}/s == 1/s, By{transmitted}/s == By/s.
  • NAME è una sequenza di caratteri ASCII stampabili non vuoti che non contengono { o }.
  • 1 rappresenta un'unità adimensionale unitaria di 1, ad esempio in 1/s. Viene in genere utilizzata quando nessuna delle unità di base è appropriata. Ad esempio, "nuovi utenti al giorno" può essere rappresentato come 1/d o {new-users}/d (e un valore della metrica 5 significherebbe "5 nuovi utenti"). In alternativa, "migliaia di visualizzazioni di pagina al giorno" sarebbero rappresentate come 1000/d o k1/d o k{page_views}/d (e un valore della metrica pari a 5.3 significherebbe "5300 visualizzazioni di pagina al giorno").
  • % rappresenta il valore adimensionale di 1/100 e annota i valori che danno una percentuale (quindi i valori delle metriche sono in genere compresi tra 0 e 100 e un valore della metrica 3 significa "3 percento").
  • 10^2.% indica che una metrica contiene un rapporto, in genere nell'intervallo 0-1, che verrà moltiplicato per 100 e visualizzato come percentuale (quindi un valore della metrica 0.03 significa "3 percento").
description

string

Una descrizione dettagliata della metrica, che può essere utilizzata nella documentazione.

displayName

string

Un nome conciso per la metrica, che può essere visualizzato nelle interfacce utente. Utilizza la lettera maiuscola a inizio frase senza il punto finale, ad esempio "Conteggio richieste". Questo campo è facoltativo, ma è consigliabile impostarlo per qualsiasi metrica associata a concetti visibili agli utenti, ad esempio la quota.

metadata

object (MetricDescriptorMetadata)

Facoltativo. Metadati che possono essere utilizzati per guidare l'utilizzo della metrica.

launchStage

enum (LaunchStage)

Facoltativo. La fase di lancio della definizione della metrica.

monitoredResourceTypes[]

string

Sola lettura. Se presente, un time series, identificato parzialmente da un tipo di metrica e da un MonitoredResourceDescriptor, associato a questo tipo di metrica può essere associato solo a uno dei tipi di risorsa monitorata elencati qui.

LabelDescriptor

Rappresentazione JSON
{
  "key": string,
  "valueType": enum (ValueType),
  "description": string
}
Campi
key

string

La chiave per questa etichetta. La chiave deve soddisfare i seguenti criteri:

  • Non supera i 100 caratteri.
  • Corrisponde alla seguente espressione regolare: [a-zA-Z][a-zA-Z0-9_]*
    • Il primo carattere deve essere una lettera maiuscola o minuscola.
    • I caratteri rimanenti devono essere lettere, cifre o trattini bassi.
valueType

enum (ValueType)

Il tipo di dati che può essere assegnato all'etichetta.

description

string

Una descrizione leggibile per l'etichetta.

MetricDescriptorMetadata

Rappresentazione JSON
{
  "launchStage": enum (LaunchStage),
  "samplePeriod": string,
  "ingestDelay": string,
  "timeSeriesResourceHierarchyLevel": [
    enum (TimeSeriesResourceHierarchyLevel)
  ]
}
Campi
launchStage
(deprecated)

enum (LaunchStage)

Deprecato. Devi utilizzare invece MetricDescriptor.launch_stage.

samplePeriod

string (Duration format)

Il periodo di campionamento dei punti dati della metrica. Per le metriche scritte periodicamente, i punti dati consecutivi vengono archiviati a questo intervallo di tempo, escludendo la perdita di dati dovuta a errori. Le metriche con una granularità più elevata hanno un periodo di campionamento più breve.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

ingestDelay

string (Duration format)

Il ritardo dei punti dati causato dall'importazione. I punti dati precedenti a questa data vengono acquisiti e sono disponibili per la lettura, esclusa la perdita di dati dovuta a errori.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

timeSeriesResourceHierarchyLevel[]

enum (TimeSeriesResourceHierarchyLevel)

L'ambito dei dati delle serie temporali della metrica.

Durata

Rappresentazione JSON
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Secondi firmati dell'intervallo di tempo. Deve essere compreso tra -315.576.000.000 e +315.576.000.000 inclusi. Nota: questi limiti vengono calcolati in base a: 60 sec/min * 60 min/ora * 24 ore/giorno * 365,25 giorni/anno * 10.000 anni

nanos

integer

Frazioni di secondo con segno con risoluzione in nanosecondi dell'intervallo di tempo. Le durate inferiori a un secondo sono rappresentate con un campo seconds pari a 0 e un campo nanos positivo o negativo. Per durate di un secondo o più, un valore diverso da zero per il campo nanos deve avere lo stesso segno del campo seconds. Deve essere compreso tra -999.999.999 e +999.999.999 inclusi.

ValueType

Tipi di valori che possono essere utilizzati come valori etichetta.

Enum
STRING Una stringa di lunghezza variabile, non superiore a 1024 caratteri. Questo è il tipo di valore predefinito.
BOOL Booleano; vero o falso.
INT64 Un numero intero a 64 bit con segno.

MetricKind

Il tipo di misurazione. Descrive come vengono riportati i dati. Per informazioni sull'impostazione dell'ora di inizio e di fine in base a MetricKind, vedi TimeInterval.

Enum
METRIC_KIND_UNSPECIFIED Non utilizzare questo valore predefinito.
GAUGE Una misurazione istantanea di un valore.
DELTA La variazione di un valore durante un intervallo di tempo.
CUMULATIVE Un valore accumulato in un intervallo di tempo. Le misurazioni cumulative in una serie temporale devono avere la stessa ora di inizio e ore di fine crescenti, finché un evento non reimposta il valore cumulativo su zero e non imposta una nuova ora di inizio per i punti successivi.

ValueType

Il tipo di valore di una metrica.

Enum
VALUE_TYPE_UNSPECIFIED Non utilizzare questo valore predefinito.
BOOL Il valore è un valore booleano. Questo tipo di valore può essere utilizzato solo se il tipo di metrica è GAUGE.
INT64 Il valore è un numero intero a 64 bit con segno.
DOUBLE Il valore è un numero con rappresentazione in virgola mobile a precisione doppia.
STRING Il valore è una stringa di testo. Questo tipo di valore può essere utilizzato solo se il tipo di metrica è GAUGE.
DISTRIBUTION Il valore è un Distribution.
MONEY Il valore è denaro.

LaunchStage

La fase di lancio definita in Fasi di lancio di Google Cloud Platform.

Enum
LAUNCH_STAGE_UNSPECIFIED Non utilizzare questo valore predefinito.
UNIMPLEMENTED La funzionalità non è ancora implementata. Gli utenti non possono utilizzarlo.
PRELAUNCH Le funzionalità pre-lancio sono nascoste agli utenti e sono visibili solo internamente.
EARLY_ACCESS Le funzionalità di accesso in anteprima sono limitate a un gruppo chiuso di tester. Per utilizzare queste funzionalità, devi registrarti in anticipo e firmare un contratto di Trusted Tester (che include disposizioni sulla riservatezza). Queste funzionalità possono essere instabili, essere modificate in modi incompatibili con le versioni precedenti e non ne è garantito il rilascio.
ALPHA Alpha è un test a disponibilità limitata per le release prima che sia autorizzato un uso più ampio. Nella versione Alpha, tutti i problemi di progettazione significativi vengono risolti e stiamo verificando la funzionalità. I clienti alpha devono richiedere l'accesso, accettare i termini applicabili e inserire i propri progetti nella lista consentita. Le versioni alpha non sono necessariamente complete di tutte le funzionalità. Inoltre, non prevedono SLA (accordi sul livello del servizio) né obblighi di assistenza tecnica, ma sono sufficientemente avanzate da consentire ai clienti di utilizzarle in ambienti di test o per test a uso limitato, proprio come farebbero in normali casi di produzione.
BETA La versione beta è il punto in cui siamo pronti ad aprire una release per l'utilizzo da parte di qualsiasi cliente. Nelle versioni beta non sono previsti SLA (accordi sul livello del servizio) né obblighi di assistenza tecnica. I prodotti saranno completi dal punto di vista delle funzionalità, ma potrebbero presentare alcuni problemi ancora da risolvere. Le versioni beta sono adatte a casi d'uso di produzione limitati.
GA Le funzionalità GA sono aperte a tutti gli sviluppatori e sono considerate stabili e completamente qualificate per l'uso in produzione.
DEPRECATED Le funzionalità deprecate verranno sospese e rimosse. Per ulteriori informazioni, consulta la sezione "Norme sul ritiro" dei nostri Termini di servizio e la documentazione Piattaforma Google Cloud soggetta alle norme sul ritiro.

TimeSeriesResourceHierarchyLevel

Il livello della gerarchia di risorse dei dati delle serie temporali di una metrica.

Enum
TIME_SERIES_RESOURCE_HIERARCHY_LEVEL_UNSPECIFIED Non utilizzare questo valore predefinito.
PROJECT Limita l'ambito di una metrica a un progetto.
ORGANIZATION Limita l'ambito di una metrica a un'organizzazione.
FOLDER Limita l'ambito di una metrica a una cartella.

Annotazioni dello strumento

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌