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 usati dalle metriche incorporate 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 dove hanno avuto origine i punti dati.
Le metriche definite dall'utente, a volte chiamate metriche personalizzate, possono essere usate come le metriche integrate. Ciò significa che puoi creare grafici e avvisi per questi dati delle metriche.
Per implementare la tua applicazione, ti consigliamo di utilizzare un framework di strumentazione open source indipendente dal fornitore, come OpenTelemetry, anziché API o librerie client specifiche del fornitore e del prodotto. Per informazioni sulla strumentazione della tua applicazione, consulta Strumentazione e osservabilità.
Prima di iniziare
Per scoprire di più sulle strutture alla base di tutte le metriche, consulta Metriche, serie temporali e risorse
Per utilizzare Cloud Monitoring, devi avere un progetto Google Cloud con fatturazione abilitata. Se necessario:
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
- Assicurati che l'API Monitoring sia abilitata. Per maggiori dettagli, consulta Abilitazione dell'API Monitoring.
Per le applicazioni in esecuzione al di fuori di Google Cloud, il progetto Google Cloud deve autenticare l'applicazione. In genere, l'autenticazione viene configurata creando un account di servizio per il progetto e configurando una variabile di ambiente.
Per le applicazioni eseguite su un'istanza Amazon Elastic Compute Cloud (Amazon EC2), crea l'account di servizio per il progetto del connettore AWS dell'istanza.
Per informazioni sulla creazione di un account di servizio, consulta la Guida introduttiva all'autenticazione.
Crea un tipo di metrica definito dall'utente
Per creare una metrica definita dall'utente, puoi definire un oggetto MetricDescriptor
che specifica varie informazioni sulla metrica oppure scrivere i relativi dati. Quando scrivi i dati delle metriche, Monitoring crea per te il descrittore della metrica in base alla struttura dei dati che fornisci.
Per informazioni sulla progettazione di un descrittore della metrica, consulta
Descrittori delle metriche per le metriche definite dall'utente.
Creazione automatica dei descrittori delle metriche
Se scrivi dati di una metrica quando non esiste ancora un descrittore 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 volevi. La creazione automatica dei descrittori delle metriche comporta alcuni presupposti e valori predefiniti.
Cloud Monitoring crea un nuovo MetricDescriptor
quando
l'oggetto TimeSeries
incluso in una chiamata a
timeSeries.create
fa riferimento a un
oggettoMetric
che specifica un
nome del tipo di metrica inesistente.
Cloud Monitoring utilizza le seguenti regole per completare il
MetricDescriptor
:
type
: il tipo viene copiato dal campotype
dell'oggettoMetric
.name
: il nome viene creato a partire 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 include i seguenti campi:key
: la chiave di etichetta nell'oggettoMetric
.valueType
:STRING
description
: non impostato
metricKind
: il tipo di metrica è impostato suGAUGE
a meno che non specifichi il parametrometricKind
dell'oggettoTimeSeries
. Quando specifichimetricKind
, la nuova metrica include questo tipo. Puoi specificare solo i tipiGAUGE
eCUMULATIVE
.valueType
: il tipo di valore viene recuperato dal valore digitato diPoint
che stai scrivendo. 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 composte dall'unione di tutte le etichette
negli oggetti Metric
in tutte le serie temporali in questa chiamata a
create
.
Passaggio successivo: consulta 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 effettuare queste scelte, puoi sfogliare le metriche integrate e esaminare i dati delle relative 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 console Google Cloud.
Scegli uno o più 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 in ogni progetto.
Per scrivere metriche definite dall'utente dalle risorse gestite da un account AWS, crea il descrittore della metrica nel progetto del connettore AWS per quell'account.
Determina il tipo di metrica, il tipo di valore e, facoltativamente, le unità. Non tutti i tipi di valori e di metriche sono supportati per le metriche definite dall'utente. Per ulteriori informazioni su questi campi, consulta Tipi di valore e di metriche.
Scegli le etichette della metrica: nomi, tipi di valori e descrizioni.
Determinare le risorse monitorate su cui vengono scritti i dati delle metriche. Scegli dall'elenco seguente:
aws_ec2_instance
: istanza Amazon EC2.dataflow_job
: job di Dataflow.gae_instance
: istanza di App Engine.gce_instance
: istanza Compute Engine.generic_node
: nodo di computing specificato dall'utente.generic_task
: attività definita dall'utente.gke_container
: istanza di 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
e poi passalo come argomento a una chiamata al metodometricDescriptors.create
.
Di solito si tratta di un errore chiamare metricDescriptors.create
utilizzando lo stesso nome di tipo 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 indicatore.
Protocollo
Per creare un descrittore della metrica, utilizza il metodo metricDescriptors.create
.
Puoi eseguire questo metodo utilizzando il widget Explorer API nella pagina di riferimento del metodo. Per saperne di più, 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 nel widget, utilizzando l'ID del progetto
al posto di [PROJECT_ID
]:
Fai clic sul pulsante Execute (Esegui) per eseguire il metodo.
Quando crei una nuova metrica, il campo name
nella
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, devi utilizzare questo nome.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta l'articolo Risolvere i problemi relativi alle chiamate API.
Passaggio successivo: consulta Scrivere metriche definite dall'utente.
Scrivere metriche definite dall'utente
Puoi scrivere dati solo nei tipi di metrica per le metriche definite dall'utente. Per scrivere i dati,
utilizza il metodo timeSeries.create
.
In presenza di una serie temporale, questo metodo aggiunge
un nuovo punto dati a quella esistente. Quando la serie temporale non esiste, questo metodo la crea e aggiunge i dati.
Puoi scrivere 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
; vengono ignorati durante la scrittura dei punti dati. Ogni oggetto
TimeSeries
deve contenere un solo oggettoPoint
:- Il valore del punto e l'intervallo di tempo devono essere coerenti con la definizione del tipo di metrica. Per informazioni sugli intervalli di tempo per 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 superare le 25 ore nel passato o non più di cinque minuti nel futuro.
- Il valore del punto e l'intervallo di tempo devono essere coerenti con la definizione del tipo di metrica. Per informazioni sugli intervalli di tempo per diversi tipi di metriche, consulta
Per scrivere più punti 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 esistono limitazioni di frequenza.
Protocollo
Per scrivere i dati delle metriche, utilizza il metodo timeSeries.create
.
Puoi eseguire questo metodo utilizzando il widget Explorer API nella pagina di riferimento del metodo. Per saperne di più, consulta Explorer API.
Per scrivere un punto alla metrica stores/daily_sales
creata nella sezione
Creazione manuale di descrittori delle metriche:
- Vai alla pagina di riferimento per
timeSeries.create
. - Fornisci i parametri seguenti al widget Explorer API.
- Fai clic sul pulsante Esegui.
Utilizza i seguenti parametri di esempio:
- nome:
projects/[PROJECT_ID]
request body: includi un elenco di oggetti
TimeSeries
. L'esempio seguente contiene una sola serie temporale.{ "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 a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta l'articolo Risolvere i problemi relativi alle chiamate API.
Elimina 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 progetto Google Cloud. Tuttavia, l'eliminazione del descrittore della metrica rende i dati inaccessibili. I dati scadono e vengono eliminati in base alle norme sulla conservazione dei dati.
Non puoi eliminare il descrittore della metrica per 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 Explorer API nella pagina di riferimento del metodo. Per saperne di più, consulta Explorer API.
Per eliminare la metrica stores/daily_sales
creata in
Creazione manuale di descrittori delle metriche:
- Vai alla pagina di riferimento per
metricDescriptors.delete
: Fornisci il nome del descrittore della metrica al widget Explorer API:
nome:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
Fai clic sul pulsante Esegui.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta l'articolo Risolvere i problemi relativi alle chiamate API.
Modificare una metrica definita dall'utente
Per modificare una metrica definita dall'utente, devi aggiornare l'oggetto MetricDescriptor
che la definisce.
L'unica modifica supportata è l'aggiunta di etichette.
Per aggiungere etichette a una metrica esistente definita dall'utente, 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 non vuoi fare altro che aggiungere nuove etichette, devi eliminare e ricreare il descrittore della metrica. In questo caso, perderai tutti i dati delle serie temporali precedentemente raccolti per il descrittore della metrica precedente. Per saperne di più, consulta Eliminare le metriche definite dall'utente.
Non puoi rinominare una metrica.
Passaggi successivi
- Visualizzare l'utilizzo e la diagnostica delle metriche
- Elenco di metriche integrate
- Elenco di risorse monitorate