Ce document explique comment lire des données de métriques, également appelées données de séries temporelles,
à l'aide de la méthode timeSeries.list
dans
API Monitoring.
Il existe plusieurs façons d'appeler la méthode timeSeries.list
:
- Les onglets Protocole de cette page vous permettent d'utiliser le protocole APIs Explorer :
- Vous pouvez utiliser une bibliothèque cliente spécifique à un langage.
- Vous pouvez utiliser l'explorateur de métriques.
Vous pouvez également envoyer une commande à la méthode timeSeries.query
pour lire vos données de métriques. Pour ce faire, vous devez utiliser le langage MQL (Monitoring Query Language). Ce document ne décrit pas
MQL ou la méthode timeSeries.query
. Pour en savoir plus sur ces sujets, consultez la section Récupérer des données avec timeSeries.query
.
Présentation
Chaque appel de la méthode timeSeries.list
peut renvoyer n'importe quel nombre de séries temporelles à partir d'un seul type de métrique. Par exemple, si vous utilisez Compute Engine, le type de métrique compute.googleapis.com/instance/cpu/usage_time
dispose d'une série temporelle distincte pour chacune de vos instances de VM.
Pour une introduction aux métriques et aux séries temporelles,
Consultez la section Métriques, séries temporelles et ressources.
Vous spécifiez les données de séries temporelles souhaitées en fournissant les informations suivantes à la méthode timeSeries.list
:
- Une expression de filtre qui spécifie le type de métrique. Le filtre peut éventuellement permettre de sélectionner un sous-ensemble de séries temporelles de la métrique, si vous spécifiez les ressources à l'origine des séries temporelles recherchées, ou si vous spécifiez des valeurs pour certains de leurs libellés.
- Un intervalle de temps qui limite la quantité de données renvoyée.
- Une manière de combiner plusieurs séries temporelles afin de produire un résumé global des données (facultatif). Pour en savoir plus et exemples, consultez la section Agréger des données.
Filtres de séries temporelles
Pour spécifier les séries temporelles à récupérer, transmettez un filtre de série temporelle à la méthode timeSeries.list
.
Voici une liste des composants de filtre courants:
Le filtre doit spécifier un seul type de métrique. Exemple :
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Pour récupérer des métriques définies par l'utilisateur, modifiez le préfixe "metric.type" dans filter sur
custom.googleapis.com
ou sur un autre préfixe si utilisé.external.googleapis.com
est fréquemment utilisé.Le filtre peut spécifier des valeurs pour les libellés de variables de la métrique. Le type de métrique détermine quels libellés sont disponibles. Exemple :
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
Dans l'expression précédente,
label
est correct même si l'objet de métrique réel utiliselabels
comme clé.Le filtre ne peut sélectionner que les séries temporelles qui contiennent un type de ressource surveillée spécifique:
resource.type = "gce_instance"
Tous ces composants peuvent être combinés pour former un filtre de série temporelle unique. Exemple :
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")
Si vous ne spécifiez pas de valeurs pour tous les libellés de métrique, la méthode list
renvoie une série temporelle pour chaque combinaison de valeurs dans les libellés non spécifiés. Notez que la méthode ne renvoie que des séries temporelles contenant des données.
Intervalles de temps
Lorsque vous utilisez l'API pour lire des données, vous spécifiez l'intervalle de temps pour lequel vous souhaitez récupérer les données en définissant les heures de début et de fin.
L'API extrait les données de l'intervalle (start, end]
, c'est-à-dire après l'heure de début jusqu'à l'heure de fin.
L'heure de début ne doit pas être ultérieure à l'heure de fin. Si vous spécifiez une heure de début ultérieure à l'heure de fin, l'API renvoie une erreur.
Si vous souhaitez ne récupérer que les données qui présentent un horodatage spécifique, définissez l'heure de début sur l'heure de fin ou ne définissez pas l'heure de début.
Format horaire
Les heures de début et de fin doivent être spécifiées en tant que chaînes au format RFC 3339. Exemple :
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
La commande date -Iseconds
sous Linux est utile pour générer des horodatages.
Opérations de listes de base
La méthode timeSeries.list
permet de
des données brutes simples
pour renvoyer des données hautement traitées. Cette section explique comment lister les séries temporelles disponibles et comment obtenir les valeurs d'une série temporelle spécifique.
Exemple : Répertorier les séries temporelles disponibles
Cet exemple montre comment répertorier uniquement les noms et les descriptions de la série temporelle correspondant à un filtre, plutôt que de renvoyer toutes les données disponibles :
Protocole
Ouvrez la page de référence
timeSeries.list
.Dans le volet Essayer cette méthode, saisissez ce qui suit :
-
name : saisissez le chemin d'accès à votre projet.
projects/PROJECT_ID
-
filter: spécifiez le type de métrique.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime : saisissez l'heure de fin.
- interval.startTime : saisissez l'heure de début et assurez-vous qu'elle est 20 minutes antérieure à l'heure de fin.
Cliquez sur Afficher les paramètres standards, puis dans champs, saisissez les éléments suivants :
timeSeries.metric
-
name : saisissez le chemin d'accès à votre projet.
Cliquez sur Exécuter.
L'exemple de résultat ci-dessous montre les séries temporelles de deux instances de VM différentes :
{
"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"
},
}
]
}
Pour afficher la requête en tant que commande curl
, en tant que requête HTTP ou en JavaScript, cliquez sur fullscreen Plein écran dans APIs Explorer.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Ruby
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Si vous rencontrez des difficultés, consultez la section Dépannage de l'API Monitoring.
Exemple : Obtenir des données de séries temporelles
Cet exemple renvoie les mesures d'utilisation du processeur enregistrées sur une période de 20 minutes pour une instance Compute Engine spécifique. La quantité de données renvoyées dépend du taux d'échantillonnage de la métrique. En effet, l'utilisation du CPU est échantillonnée toutes les minutes, les résultats de cette requête représente environ 20 points de données. Lorsque plusieurs points de données sont renvoyés pour une série temporelle, l'API renvoie les points de données de chaque série temporelle en remontant dans le temps. Aucun dépassement n'a été défini pour ce tri des points.
Protocole
L'exemple de protocole limite davantage la sortie, pour que le code plus gérables des données dans la zone de réponse:
- La valeur filter limite la série temporelle à une seule instance de VM.
- La valeur du paramètre fields spécifie uniquement l'heure et la valeur des mesures.
Ces paramètres limitent la quantité de données de séries temporelles renvoyées dans le résultat.
Ouvrez la page de référence
timeSeries.list
.Dans le volet Essayer cette méthode, saisissez ce qui suit :
-
name : saisissez le chemin d'accès à votre projet.
projects/PROJECT_ID
filter : spécifiez le type de métrique.
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime : saisissez l'heure de fin.
interval.startTime : saisissez l'heure de début et assurez-vous qu'elle est 20 minutes antérieure à l'heure de fin.
Cliquez sur Afficher les paramètres standards, puis dans champs, saisissez les éléments suivants :
timeSeries.points.interval.endTime,timeSeries.points.value
-
name : saisissez le chemin d'accès à votre projet.
Cliquez sur Exécuter.
La requête renvoie un résultat semblable aux lignes suivantes :
{
"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
}
}
]
}
]
}
Pour afficher la requête sous la forme d'une commande curl
,
ou en JavaScript, cliquez sur fullscreen Plein écran
dans APIs Explorer.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Ruby
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
En cas de problème, consultez Dépannez l'API Monitoring.
Agréger des données
La méthode timeSeries.list
permet d'effectuer des réductions et des agrégations statistiques sur les données de séries temporelles renvoyées. Les sections suivantes illustrent deux exemples.
Pour en savoir plus, consultez la section Filtrage et agrégation : manipuler des séries temporelles.
Exemple : Aligner des séries temporelles
Cet exemple permet de réduire les 20 mesures d'utilisation individuelles effectuées dans chaque série temporelle à deux mesures. Vous obtenez ainsi l'utilisation moyenne pour les deux périodes de 10 minutes comprises dans l'intervalle total de 20 minutes. Les données de chaque série temporelle sont d'abord alignées sur des périodes de 10 minutes, puis la moyenne des valeurs de chaque période de 10 minutes est calculée.
L'opération d'alignement présente deux avantages : elle lisse les données et aligne les données de toutes les séries temporelles sur 10 minutes exactement. Les données alignées peuvent ensuite être traitées.
Protocole
Ouvrez la page de référence sur
timeSeries.list
.Dans le volet Essayer cette méthode, saisissez ce qui suit :
-
name: saisissez le chemin d'accès à votre projet.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: saisissez
600s
-
aggregation.perSeriesAligner: sélectionnez
ALIGN_MEAN
-
filter: spécifiez le type de métrique.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime : saisissez l'heure de fin.
- interval.startTime : saisissez l'heure de début et assurez-vous qu'elle est 20 minutes antérieure à l'heure de fin.
-
Cliquez sur Afficher les paramètres standards, puis dans champs, saisissez les éléments suivants :
timeSeries.metric,timeSeries.points
-
name: saisissez le chemin d'accès à votre projet.
Cliquez sur Exécuter.
Le filtre pour une seule instance, présenté dans l'exemple précédent, est supprimé : cette requête renvoie beaucoup moins de données. La nécessité de la limiter à une seule instance de VM est donc moindre.
L'exemple de résultat suivant affiche une série temporelle pour chacune des trois instances de VM. Chaque série temporelle comporte deux points de données, l'utilisation moyenne pour les périodes d'alignement de 10 minutes :
{
"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 }
}
]
}
]
}
Pour afficher la requête en tant que commande curl
, en tant que requête HTTP ou en JavaScript, cliquez sur fullscreen Plein écran dans APIs Explorer.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Ruby
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Si vous rencontrez des difficultés, consultez la section Dépannage de l'API Monitoring.
Exemple : Réduire toutes les séries temporelles
La section qui suit reprend l'exemple précédent, et combine les séries temporelles alignées des trois instances de VM en une seule série temporelle affichant l'utilisation moyenne de toutes les instances.
Protocole
Ouvrez la page de référence sur
timeSeries.list
.Dans le volet intitulé Try this method (Essayer cette méthode), saisissez la commande suivante:
-
name: saisissez le chemin d'accès à votre projet.
projects/PROJECT_ID
-
aggregation.alignmentPeriod: saisissez
600s
-
aggregation.perSeriesAligner : sélectionnez
ALIGN_MEAN
-
aggregation.crossSeriesReducer: sélectionnez
REDUCE_MEAN
. -
filter: spécifiez le type de métrique.
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime : saisissez l'heure de fin.
- interval.startTime : saisissez l'heure de début et assurez-vous qu'elle est 20 minutes antérieure à l'heure de fin.
-
Cliquez sur Afficher les paramètres standards, puis dans champs, saisissez les éléments suivants :
timeSeries.metric,timeSeries.points
-
name: saisissez le chemin d'accès à votre projet.
Cliquez sur Exécuter.
Ainsi, le résultat ci-dessous comporte une seule série temporelle et uniquement deux points de données. Chaque point représente la moyenne d'utilisation entre les trois instances de VM au cours de la période :
{
"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
}
}
]
}
]
}
Pour afficher la requête sous la forme d'une commande curl
,
ou en JavaScript, cliquez sur fullscreen Plein écran
dans APIs Explorer.
C#
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Go
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Node.js
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
PHP
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Python
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Ruby
Pour vous authentifier auprès de Monitoring, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
En cas de problème, consultez Dépannez l'API Monitoring.
Étape suivante
- Apprenez-en plus sur la conservation et la latence des données de métriques.
- Découvrez Filtrage et agrégation : manipuler des séries temporelles.