Questo documento descrive come creare metriche definite dall'utente e come scrivere questi dati delle metriche utilizzando l'API Cloud Monitoring. Le metriche definite dall'utente utilizzano gli stessi elementi delle metriche integrate di Cloud Monitoring:
- Un insieme di punti dati.
- Informazioni sul tipo di metrica, che indicano cosa rappresentano i punti dati.
- Informazioni sulle risorse monitorate, che indicano l'origine dei punti dati.
Le metriche definite dall'utente, a volte chiamate metriche personalizzate, possono essere utilizzate allo stesso modo delle metriche integrate. ovvero puoi creare grafici e avvisi per questi dati delle metriche.
Le metriche basate su log sono una classe di metriche definite dall'utente, ma non puoi crearle utilizzando l'API Cloud Monitoring. Le metriche basate su log derivano i dati delle metriche dalle voci di log, ma l'API Monitoring non fornisce alcun modo per specificare come estrarre i dati delle metriche dalle voci di log. Utilizza invece Cloud Logging per creare metriche basate su log. Quando crei una metrica basata su log, Logging crea le strutture descritte in questo documento e invia i dati della metrica a Cloud Monitoring. Per informazioni sulla creazione di metriche basate su log, consulta i seguenti documenti:
Per instrumentare l'applicazione, ti consigliamo di utilizzare un framework di instrumentazione indipendente dal fornitore e open source, come OpenTelemetry, anziché API o librerie client specifiche per fornitori e prodotti. Per informazioni sulla strumentazione dell'applicazione, vedi Strumentazione e osservabilità.
Prima di iniziare
Per scoprire le strutture alla base di tutte le metriche, consulta Metriche, serie temporali e risorse.
Per utilizzare Cloud Monitoring, devi avere un Google Cloud progetto con la fatturazione abilitata. Se necessario, procedi nel seguente modo:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Assicurati che l'API Monitoring sia abilitata. Per maggiori dettagli, vedi Attivazione dell'API Monitoring.
- Per le applicazioni eseguite al di fuori di Google Cloud, il tuo progetto Google Cloud deve autenticare l'applicazione utilizzando le Credenziali predefinite dell'applicazione (ADC) locali. Per saperne di più, vedi Configurare ADC per on-premise o un altro provider cloud.
Creare un tipo di metrica definito dall'utente
Per creare una metrica definita dall'utente, devi definire un oggetto
MetricDescriptor
che specifica varie informazioni sulla metrica oppure scrivere i dati della metrica. Quando scrivi i dati delle metriche,
Monitoring crea il descrittore della metrica in base
alla struttura dei dati che fornisci.
Per informazioni sulla progettazione di un descrittore della metrica, vedi
Descrittori di metriche per le metriche definite dall'utente.
Creazione automatica dei descrittori delle metriche
Se scrivi dati delle metriche quando non esiste ancora un descrittore della metrica per quella metrica definita dall'utente, viene creato automaticamente un descrittore della metrica. Tuttavia, questo nuovo descrittore della metrica potrebbe non essere esattamente quello che vuoi; la creazione automatica dei descrittori delle metriche comporta alcune ipotesi e valori predefiniti.
Cloud Monitoring crea un nuovo MetricDescriptor
quando
l'oggetto TimeSeries
incluso in una chiamata a
timeSeries.create
fa riferimento a un
oggetto Metric
che specifica un
nome del tipo di metrica inesistente.
Cloud Monitoring utilizza le seguenti regole per compilare
MetricDescriptor
:
type
: il tipo viene copiato dal campotype
dell'oggettoMetric
.name
: il nome viene creato dall'ID progetto nella chiamata al metodo e dal valore ditype
nell'oggettoMetric
.labels
: le etichette visualizzate nell'oggettoMetric
. Ogni descrittore di etichetta nel nuovo descrittore della metrica ha i seguenti campi:key
: la chiave dell'etichetta nell'oggettoMetric
.valueType
:STRING
description
: non impostato
metricKind
: il tipo di metrica è impostato suGAUGE
, a meno che tu non specifichi il parametrometricKind
dell'oggettoTimeSeries
. Quando specifichimetricKind
, la nuova metrica ha questo tipo. Puoi specificare solo i tipiGAUGE
eCUMULATIVE
.valueType
: il tipo di valore viene ricavato dal valore digitato diPoint
in fase di scrittura. Il tipo di valore deve essereBOOL
,INT64
,DOUBLE
oDISTRIBUTION
. Quando specifichi un tipo di valore nel campovalueType
diTimeSeries
, questo tipo deve corrispondere al tipo diPoint
.unit
: non impostatodescription
:"Auto created custom metric."
.displayName
: non impostato
In una singola chiamata timeSeries.create
, puoi includere più oggetti TimeSeries
che fanno riferimento allo stesso tipo di metrica inesistente. In questo caso,
le etichette nel nuovo descrittore della metrica sono costituite dall'unione di tutte le etichette
negli oggetti Metric
in tutte le serie temporali in questa chiamata a
create
.
Passaggio successivo: consulta la sezione Scrivere metriche definite dall'utente.
Creazione manuale dei descrittori delle metriche
Per creare un descrittore della metrica:
Determina la struttura del descrittore della metrica. Per aiutarti a fare queste scelte, puoi sfogliare le metriche integrate e consultare i relativi dati delle serie temporali:
Scegli un nome della metrica per la metrica definita dall'utente.
Scegli un nome visualizzato e una descrizione per la metrica. Il nome visualizzato viene utilizzato nella Google Cloud console.
Scegli un progetto o dei progetti in cui definire la metrica definita dall'utente e scrivere i relativi dati delle serie temporali. Quando hai bisogno della stessa metrica in più progetti, crea definizioni identiche della metrica in ogni progetto.
Determina il tipo, il tipo di valore e (facoltativamente) le unità della metrica. Non tutti i tipi di valori e i tipi di metriche sono supportati per le metriche definite dall'utente. Per ulteriori informazioni su questi campi, consulta Tipi di valori e tipi di metriche.
Scegli le etichette della metrica: i relativi nomi, tipi di valori e descrizioni.
Determina le risorse monitorate rispetto alle quali vengono scritti i dati delle metriche. Scegli dall'elenco seguente:
aws_ec2_instance
: Istanza Amazon EC2.dataflow_job
: Job Dataflow.gae_instance
: Istanza App Engine.gce_instance
: Istanza Compute Engine.generic_node
: Nodo di computing specificato dall'utente.generic_task
: Attività definita dall'utente.gke_container
: Istanza container GKE.global
: Utilizza questa risorsa quando nessun altro tipo di risorsa è adatto. Per la maggior parte dei casi d'uso,generic_node
ogeneric_task
sono scelte migliori rispetto aglobal
.k8s_cluster
: Cluster Kubernetes.k8s_container
: Container Kubernetes.k8s_node
: Nodo Kubernetes.k8s_pod
: Pod Kubernetes.
Crea un oggetto
MetricDescriptor
, quindi passalo come argomento a una chiamata al metodometricDescriptors.create
.
Di solito è un errore chiamare
metricDescriptors.create
utilizzando lo stesso tipo
nome di un descrittore della metrica esistente. Tuttavia, se tutti i campi del nuovo oggetto MetricDescriptor
corrispondono esattamente ai campi del descrittore esistente, non si tratta di un errore, ma non ha alcun effetto.
Nell'esempio seguente, crei una metrica di tipo indicatore.
Protocollo
Per creare un descrittore della metrica, utilizza il
metodo metricDescriptors.create
.
Puoi eseguire questo metodo utilizzando il widget APIs Explorer nella
pagina di riferimento del metodo. Per ulteriori informazioni, consulta Explorer API.
Di seguito sono riportati i parametri di esempio per
metricDescriptors.create
:
- name (URL):
projects/[PROJECT_ID]
Corpo della richiesta: fornisci un oggetto
MetricDescriptor
come il seguente:{ "name": "", "description": "Daily sales records from all branch stores.", "displayName": "Sales", "type": "custom.googleapis.com/stores/sales", "metricKind": "GAUGE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
Fornisci questi valori ai campi del widget, utilizzando l'ID del tuo progetto
al posto di [PROJECT_ID
:
Fai clic sul pulsante Esegui per eseguire il metodo.
Quando crei una nuova metrica, il campo name
in
MetricDescriptor
viene ignorato e può essere omesso. Il metodo create
restituisce
il nuovo descrittore della metrica con il campo name
compilato, che in questo
esempio sarebbe il seguente:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
Se, ad esempio, vuoi ottenere il descrittore di una metrica, utilizza questo nome.
C#
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta Risolvere i problemi relativi alle chiamate API se hai difficoltà.
Passaggio successivo: consulta la sezione Scrivere metriche definite dall'utente.
Scrivere metriche definite dall'utente
Puoi scrivere dati solo nei tipi di metriche per le metriche definite dall'utente. Per scrivere i dati,
utilizza il metodo timeSeries.create
.
Se la serie temporale esiste, questo
metodo aggiunge un nuovo punto dati alla serie temporale esistente. Quando la serie temporale non esiste, questo metodo la crea e aggiunge i dati.
Scrivi i punti dati passando un elenco di oggetti TimeSeries
a
timeSeries.create
.
La dimensione massima dell'elenco è 200 e ogni oggetto nell'elenco deve specificare una serie temporale diversa:
- I valori dei campi
metric
eresource
identificano un oggettoTimeSeries
specifico. Questi campi rappresentano il tipo di metrica dei dati e la risorsa monitorata da cui sono stati raccolti i dati. - Ometti i campi
metricKind
evalueType
, che vengono ignorati durante la scrittura dei punti dati. Ogni oggetto
TimeSeries
deve contenere un solo oggettoPoint
:- Il valore e l'intervallo di tempo del punto devono essere coerenti con la definizione del tipo di metrica. Per informazioni sugli intervalli di tempo per i diversi tipi di metriche, consulta
TimeInterval
. - L'intervallo di tempo del punto deve essere successivo a qualsiasi punto già presente nella serie temporale.
- L'ora di fine dell'intervallo non deve essere precedente di più di 25 ore o successiva di più di cinque minuti.
- Il valore e l'intervallo di tempo del punto devono essere coerenti con la definizione del tipo di metrica. Per informazioni sugli intervalli di tempo per i diversi tipi di metriche, consulta
Per scrivere più di un punto nella stessa serie temporale, utilizza una chiamata separata al metodo
timeSeries.create
per ogni punto. Non scrivere dati in una singola serie temporale più velocemente di un punto ogni 5 secondi. Quando aggiungi punti dati a serie temporali diverse, non è previsto alcun limite di frequenza.
Protocollo
Per scrivere i dati delle metriche, utilizza il metodo timeSeries.create
.
Puoi eseguire questo metodo utilizzando il widget APIs Explorer nella
pagina di riferimento del metodo. Per saperne di più, consulta la sezione Explorer API.
Per scrivere un punto nella metrica stores/daily_sales
creata nella sezione
Creazione manuale dei descrittori delle metriche:
- Vai alla pagina di riferimento per
timeSeries.create
. - Fornisci i parametri riportati di seguito al widget Explorer API.
- Fai clic sul pulsante Esegui.
Utilizza i seguenti parametri di esempio:
- name:
projects/[PROJECT_ID]
Corpo della richiesta: includi un elenco di oggetti
TimeSeries
. Il seguente esempio contiene una sola serie temporale nell'elenco.{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/my_metric", "labels": { "my_label": "my_value" } }, "resource": { "type": "gce_instance", "labels": { "project_id": "[PROJECT_ID]", "instance_id": "1234567890123456789", "zone": "us-central1-f" } }, "points": [ { "interval": { "endTime": "2018-06-01T10:00:00-04:00" }, "value": { "doubleValue": 123.45 } } ] } ] }
C#
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta Risolvere i problemi relativi alle chiamate API se hai difficoltà.
Eliminare le metriche definite dall'utente
Per eliminare una metrica definita dall'utente, elimina il descrittore della metrica. Non puoi eliminare i dati delle serie temporali archiviati nel tuo progetto Google Cloud ; tuttavia, l'eliminazione del descrittore della metrica rende i dati inaccessibili. I dati scadono e vengono eliminati in base ai criteri di conservazione dei dati.
Non puoi eliminare il descrittore della metrica di una metrica integrata.
Per eliminare il descrittore della metrica, chiama il metodo
metricDescriptors.delete
.
Protocollo
Per eliminare un descrittore della metrica, utilizza il
metodo metricDescriptors.delete
.
Puoi eseguire questo metodo utilizzando il widget APIs Explorer nella
pagina di riferimento del metodo. Per saperne di più, consulta la sezione Explorer API.
Per eliminare la metrica stores/daily_sales
creata in
Creazione manuale dei descrittori delle metriche:
- Vai alla
pagina di riferimento per
metricDescriptors.delete
: Fornisci il nome del descrittore della metrica al widget Explorer API:
name:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
Fai clic sul pulsante Esegui.
C#
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Consulta Risolvere i problemi relativi alle chiamate API se hai difficoltà.
Modificare una metrica definita dall'utente
Per modificare una metrica definita dall'utente, devi aggiornare l'oggetto
MetricDescriptor
che definisce la metrica.
L'unica modifica supportata è l'aggiunta di etichette.
Per aggiungere etichette a una metrica definita dall'utente esistente, utilizza il metodo
timeSeries.create
e includi le nuove etichette con i dati delle serie temporali. Le etichette vengono aggiunte al descrittore della metrica
quando le etichette che tenti di scrivere sono valide e il numero totale
di etichette è inferiore a 30.
I dati delle serie temporali vengono quindi scritti come se l'etichetta fosse presente fin dall'inizio.
Se vuoi fare di più che aggiungere nuove etichette, devi eliminare e ricreare il descrittore della metrica. In questo caso, perdi tutti i dati delle serie temporali raccolti in precedenza per il vecchio descrittore della metrica. Per ulteriori informazioni, consulta Eliminare le metriche definite dall'utente.
Non puoi rinominare una metrica.
Passaggi successivi
- Visualizzare e gestire l'utilizzo delle metriche
- Elenco delle metriche integrate
- Elenco delle risorse monitorate