Il metodo timeSeries.list nell'API Monitoring consente di recuperare, filtrare e aggregare dati di serie temporali non elaborati o elaborati in un intervallo di tempo specificato. Puoi richiamare timeSeries.list utilizzando una libreria client specifica per il linguaggio.
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.
Puoi specificare 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 delle serie temporali della metrica specificando le risorse che producono le serie temporali o specificando i valori per determinate etichette nelle serie temporali.
- 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 ulteriori informazioni ed esempi, consulta Aggregazione dei dati.
Filtri delle serie temporali
Puoi specificare le serie temporali da recuperare passando un filtro delle serie temporali al metodo timeSeries.list.
Di seguito sono elencati i componenti comuni dei filtri:
Il filtro deve specificare un singolo 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.typenel filtro incustom.googleapis.como in un altro prefisso, se utilizzato;external.googleapis.comviene 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 della metrica effettiva utilizzalabelscome 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, specifichi l'intervallo di tempo per il quale vuoi recuperare i dati impostando le ore di inizio e di fine.
L'API recupera i dati dall'intervallo (start, end], ovvero dall'ora di inizio 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 o, in modo equivalente, non impostare l'ora di inizio.
Formato ora
Le ore di inizio e 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 sugli elenchi
Il metodo timeSeries.list può essere utilizzato per restituire dati non elaborati o 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 Risolvi i problemi relativi all'API Monitoring.
Esempio: Ottenere dati di serie temporali
Questo esempio restituisce le misurazioni dell'utilizzo della CPU registrate in un intervallo di 20 minuti per un'istanza Compute Engine specifica. La quantità di dati restituiti dipende dalla frequenza di campionamento della metrica. Poiché l'utilizzo della CPU viene campionato ogni minuto, il risultato di questa query è di 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 ordine dei punti.
C#
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 Risolvi i problemi relativi all'API Monitoring.
Aggregazione dei dati
Il metodo timeSeries.list può eseguire aggregazioni e riduzioni statistiche sui dati delle serie temporali restituiti. Le sezioni seguenti mostrano due esempi.
Per scoprire di più, consulta Filtro e aggregazione: manipolazione delle serie temporali.
Esempio: allineamento delle serie temporali
Questo esempio riduce le 20 misurazioni di utilizzo individuali 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, quindi viene calcolata la media dei valori in ogni periodo di 10 minuti.
L'operazione di allineamento presenta due vantaggi: semplifica i dati e li allinea da tutte le serie temporali su limiti esatti di 10 minuti. I dati allineati possono quindi essere ulteriormente elaborati.
C#
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 Risolvi i problemi relativi all'API Monitoring.
Esempio: riduzione tra 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 saperne di più, 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 Risolvi i problemi relativi all'API Monitoring.
Passaggi successivi
- Scopri di più su Conservazione e latenza dei dati delle metriche.
- Scopri di più su Filtro e aggregazione: manipolazione delle serie temporali.