Questo documento spiega come leggere i dati delle metriche, chiamati anche dati delle serie temporali, utilizzando il metodo timeSeries.list
nell'API Monitoring.
Esistono diversi modi per chiamare il metodo timeSeries.list
:
- Puoi utilizzare le schede Protocollo in questa pagina per utilizzare Explorer API basato su moduli.
- Puoi utilizzare una libreria client specifica per il linguaggio.
- Puoi utilizzare Metrics Explorer.
Un altro modo per leggere i dati delle metriche è inviare un comando al metodo
timeSeries.query
,
che richiede il linguaggio Monitoring Query Language (MQL). Questo documento non descrive
MQL o il metodo timeSeries.query
. Per informazioni su questi argomenti, consulta Recupero dei dati con timeSeries.query
.
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 ogni istanza 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 su come combinare più serie temporali per produrre un riepilogo aggregato dei dati. Per ulteriori informazioni e esempi, consulta Aggregazione dei dati.
Filtri delle serie temporali
Specifica la serie temporale da recuperare passando un
filtro delle serie temporali al metodo
timeSeries.list
.
Di seguito sono elencati i componenti di filtro comuni:
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 con dati.
Intervalli di tempo
Quando utilizzi l'API per leggere i dati, specifica 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 a quella 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 la data di inizio uguale alla data di fine o, in alternativa, non impostare la data 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 elenco di base
Il metodo timeSeries.list
può essere utilizzato per restituire dati semplici non elaborati o 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 corrispondenti a un filtro, anziché restituire tutti i dati disponibili:
Protocollo
Apri la pagina di riferimento
timeSeries.list
.Nel riquadro Prova questo metodo, inserisci quanto segue:
-
name: inserisci il percorso del progetto.
projects/PROJECT_ID
-
filter: specifica il tipo di metrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: inserisci l'ora di fine.
- interval.startTime: inserisci l'ora di inizio e assicurati che sia 20 minuti prima dell'ora di fine.
Fai clic su Mostra parametri standard e nei campi inserisci quanto segue:
timeSeries.metric
-
name: inserisci il percorso del progetto.
Fai clic su Execute (Esegui).
L'output di esempio mostra le serie temporali per due istanze VM diverse:
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
Per visualizzare la richiesta come comando curl
, come richiesta HTTP o in JavaScript, fai clic su fullscreen Schermo intero in Explorer API.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta la sezione Risolvere i problemi dell'API Monitoring.
Esempio: acquisizione di dati delle serie temporali
Questo esempio restituisce le misurazioni dell'utilizzo della CPU registrate su 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, 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 di ogni serie temporale in ordine cronologico inverso. Non è possibile eseguire l'override di questo ordinamento dei punti.
Protocollo
L'esempio di protocollo limita ulteriormente l'output per rendere più gestibili i dati restituiti nella casella di risposta:
- Il valore filter limita la serie temporale a una singola istanza VM.
- Il valore fields specifica solo l'ora e il valore delle misurazioni.
Queste impostazioni limitano la quantità di dati delle serie temporali restituiti nel risultato.
Apri la pagina di riferimento
timeSeries.list
.Nel riquadro Prova questo metodo, inserisci quanto segue:
-
name: inserisci il percorso del progetto.
projects/PROJECT_ID
filter: specifica il tipo di metrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime: inserisci l'ora di fine.
interval.startTime: inserisci l'ora di inizio e assicurati che sia 20 minuti prima dell'ora di fine.
Fai clic su Mostra parametri standard e nei campi inserisci quanto segue:
timeSeries.points.interval.endTime,timeSeries.points.value
-
name: inserisci il percorso del progetto.
Fai clic su Execute (Esegui).
La richiesta restituisce un risultato come il seguente:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
Per visualizzare la richiesta come comando curl
, come richiesta HTTP o in JavaScript, fai clic su fullscreen Schermo intero in Explorer API.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta la sezione Risolvere i problemi dell'API Monitoring.
Aggregare i 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 singole misurazioni dell'utilizzo in ogni serie temporale a 2 misurazioni: l'utilizzo medio per i due periodi di 10 minuti nell'intervallo di 20 minuti. I dati di ogni serie temporale vengono inizialmente allineati in periodi di 10 minuti, quindi i valori di ogni periodo di 10 minuti vengono mediati.
L'operazione di allineamento presenta due vantaggi: leviga i dati e li allinea a tutti i dati delle serie temporali su confini esatti di 10 minuti. I dati allineati possono quindi essere ulteriormente elaborati.
Protocollo
Apri la pagina di riferimento
timeSeries.list
.Nel riquadro Prova questo metodo, inserisci quanto segue:
-
name: inserisci il percorso del progetto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: inserisci
600s
-
aggregation.perSeriesAligner: seleziona
ALIGN_MEAN
-
filter: specifica il tipo di metrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: inserisci l'ora di fine.
- interval.startTime: inserisci l'ora di inizio e assicurati che sia 20 minuti prima dell'ora di fine.
-
Fai clic su Mostra parametri standard e nei campi inserisci quanto segue:
timeSeries.metric,timeSeries.points
-
name: inserisci il percorso del progetto.
Fai clic su Execute (Esegui).
Il filtro per una singola istanza mostrato nell'esempio precedente viene rimosso: questa query restituisce molti meno dati, quindi non è necessario limitarla a un'unica istanza VM.
Il seguente risultato di esempio contiene una serie temporale per ciascuna delle tre istanze VM. Ogni serie temporale ha due punti dati, l'utilizzo medio per i periodi di allineamento di 10 minuti:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
Per visualizzare la richiesta come comando curl
, come richiesta HTTP o in JavaScript, fai clic su fullscreen Schermo intero in Explorer API.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta la sezione Risolvere i 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.
Protocollo
Apri la pagina di riferimento
timeSeries.list
.Nel riquadro Prova questo metodo, inserisci quanto segue:
-
name: inserisci il percorso del progetto.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: inserisci
600s
-
aggregation.perSeriesAligner: seleziona
ALIGN_MEAN
-
aggregation.crossSeriesReducer: seleziona
REDUCE_MEAN
-
filter: specifica il tipo di metrica.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime: inserisci l'ora di fine.
- interval.startTime: inserisci l'ora di inizio e assicurati che sia 20 minuti prima dell'ora di fine.
-
Fai clic su Mostra parametri standard e nei campi inserisci quanto segue:
timeSeries.metric,timeSeries.points
-
name: inserisci il percorso del progetto.
Fai clic su Execute (Esegui).
Il seguente risultato di esempio ha una sola serie temporale e due punti dati. Ogni punto è la media dell'utilizzo tra le tre istanze VM durante il periodo di tempo:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
Per visualizzare la richiesta come comando curl
, come richiesta HTTP o in JavaScript, fai clic su fullscreen Schermo intero in Explorer API.
C#
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per autenticarti in Monitoraggio, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
In caso di difficoltà, consulta la sezione Risolvere i problemi dell'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.