Questo documento spiega come leggere i dati delle metriche, chiamati anche dati delle serie temporali,
utilizzando il metodo timeSeries.list
nell'API Monitoring.
Questo documento spiega come utilizzare le librerie client per chiamare il metodo timeSeries.list
.
Panoramica
Ogni chiamata al metodo timeSeries.list
può restituire
un numero qualsiasi di serie temporali da un singolo tipo di metrica. Ad esempio, se utilizzi Compute Engine, il tipo di metrica compute.googleapis.com/instance/cpu/usage_time
ha una serie temporale separata per ciascuna delle tue istanze VM.
Per un'introduzione alle metriche e alle serie temporali,
consulta Metriche, serie temporali e risorse.
Specifica i dati delle serie temporali che ti interessano fornendo le seguenti
informazioni al metodo timeSeries.list
:
- Un'espressione di filtro che specifica il tipo di metrica. Facoltativamente, il filtro seleziona un sottoinsieme della serie temporale della metrica specificando le risorse che producono la serie temporale o specificando i valori per determinate etichette nella serie temporale.
- Un intervallo di tempo che limita la quantità di dati restituiti.
- Facoltativamente, una specifica di come combinare più serie temporali per produrre un riepilogo aggregato dei dati. Per maggiori informazioni ed esempi, consulta la sezione Aggregazione dei dati.
Filtri delle serie temporali
Specifichi le serie temporali da recuperare passando un filtro per le serie temporali al metodo timeSeries.list
.
Di seguito sono elencati i componenti comuni dei filtri:
Il filtro deve specificare un solo tipo di metrica. Ad esempio:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Per recuperare le metriche definite dall'utente, modifica il prefisso metric.type nel filtro in
custom.googleapis.com
o in un altro prefisso, se utilizzato;external.googleapis.com
viene utilizzato di frequente.Il filtro può specificare i valori per le etichette delle dimensioni della metrica. Il tipo di metrica determina quali etichette sono presenti. Ad esempio:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
Nell'espressione precedente,
label
è corretto anche se l'oggetto metrica effettivo utilizzalabels
come chiave.Il filtro può selezionare solo le serie temporali che contengono un tipo di risorsa monitorata specifico:
resource.type = "gce_instance"
I componenti del filtro possono essere combinati in un unico filtro delle serie temporali, come il seguente:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
(metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
Se non specifichi i valori per tutte le etichette delle metriche, il metodo list
restituisce una serie temporale per ogni combinazione di valori nelle etichette non specificate. Il metodo restituisce solo le serie temporali che contengono dati.
Intervalli di tempo
Quando utilizzi l'API per leggere i dati, specifica l'intervallo di tempo
per cui vuoi recuperare i dati impostando l'ora di inizio e di fine.
L'API recupera i dati dall'intervallo (start, end]
, ovvero
dopo l'ora di inizio fino all'ora di fine.
L'ora di inizio non deve essere successiva all'ora di fine. Se specifichi un'ora di inizio successiva all'ora di fine, l'API restituisce un errore.
Se vuoi recuperare solo i dati con un timestamp specifico, imposta l'ora di inizio uguale all'ora di fine oppure, in modo equivalente, non impostare l'ora di inizio.
Formato ora
L'ora di inizio e l'ora di fine devono essere specificate come stringhe nel formato RFC 3339. Ad esempio:
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
Il comando date -Iseconds
su Linux è utile per generare timestamp.
Operazioni di base con le liste
Il metodo timeSeries.list
può essere utilizzato per restituire dati semplici e non elaborati oppure per restituire dati altamente elaborati. Questa sezione illustra
come elencare le serie temporali disponibili e come ottenere i valori
in una serie temporale specifica.
Esempio: elenco delle serie temporali disponibili
Questo esempio mostra come elencare solo i nomi e le descrizioni delle serie temporali che corrispondono a un filtro, anziché restituire tutti i dati disponibili:
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
In caso di difficoltà, consulta la sezione Risoluzione dei problemi dell'API Monitoring.
Esempio: recupero dei dati delle serie temporali
Questo esempio restituisce le misurazioni dell'utilizzo della CPU registrate in un intervallo di 20 minuti per una specifica istanza Compute Engine. La quantità di dati restituiti dipende dalla frequenza di campionamento della metrica. Poiché l'utilizzo della CPU viene campionato ogni minuto, i risultati di questa query sono circa 20 punti dati. Quando vengono restituiti più punti dati per una serie temporale, l'API restituisce i punti dati in ogni serie temporale in ordine cronologico inverso. Non è possibile eseguire l'override di questo ordinamento dei punti.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
In caso di difficoltà, consulta la sezione Risoluzione dei problemi dell'API Monitoring.
Aggregazione dei dati
Il metodo timeSeries.list
può eseguire aggregazioni e riduzioni statistiche sui dati delle serie temporali restituite. Le sezioni seguenti mostrano due esempi.
Per scoprire di più, vedi
Filtro e aggregazione: manipolazione delle serie temporali.
Esempio: allineamento delle serie temporali
Questo esempio riduce le 20 misurazioni individuali dell'utilizzo in ogni serie temporale a 2 misurazioni: l'utilizzo medio per i due periodi di 10 minuti all'interno dell'intervallo di 20 minuti. I dati di ogni serie temporale vengono prima allineati in periodi di 10 minuti, poi viene calcolata la media dei valori in ogni periodo di 10 minuti.
L'operazione di allineamento presenta due vantaggi: uniforma i dati e allinea i dati di tutte le serie temporali ai limiti esatti di 10 minuti. I dati allineati possono quindi essere elaborati ulteriormente.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
In caso di difficoltà, consulta la sezione Risoluzione dei problemi dell'API Monitoring.
Esempio: riduzione nelle serie temporali
Questo esempio estende l'esempio precedente combinando le serie temporali allineate delle tre istanze VM in un'unica serie temporale che misura l'utilizzo medio di tutte le istanze.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
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.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
In caso di difficoltà, consulta la sezione Risoluzione dei problemi dell'API Monitoring.
Passaggi successivi
- Scopri di più su Conservazione e latenza dei dati delle metriche.
- Scopri di più su Filtri e aggregazione: manipolazione delle serie temporali.