Ce document explique comment lire les données de métriques, également appelées données de séries temporelles, à l'aide de la méthode timeSeries.list
dans l'API Monitoring.
Ce document explique comment utiliser les bibliothèques clientes pour appeler la méthode timeSeries.list
.
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 lire une présentation des métriques et des séries temporelles, consultez la page Métriques, séries temporelles et ressources.
Vous pouvez spécifier 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 voir des exemples, consultez 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, remplacez le préfixe "metric.type" dans le filtre par
custom.googleapis.com
ou un autre préfixe si celui-ci est 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
peut servir à renvoyer des données brutes simples ou 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 :
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
Si vous rencontrez des difficultés, consultez la page Dépanner l'API Monitoring.
Exemple : Obtenir des données de séries temporelles
Cet exemple renvoie les mesures d'utilisation du processeur enregistrées sur un intervalle 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. Étant donné que l'utilisation du processeur est échantillonnée toutes les minutes, les résultats de cette requête comportent 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.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
Si vous rencontrez des difficultés, consultez la page Dépanner 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 présentent deux exemples.
Pour en savoir plus, consultez 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 de façon plus approfondie.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
Si vous rencontrez des difficultés, consultez la page Dépanner 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.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
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.
Avant d'exécuter des exemples de code, définissez la variable d'environnement GOOGLE_CLOUD_UNIVERSE_DOMAIN
sur s3nsapis.fr
.
Si vous rencontrez des difficultés, consultez la page Dépanner l'API Monitoring.
Étapes suivantes
- En savoir plus sur la conservation et la latence des données métriques
- En savoir plus sur Filtrage et agrégation : manipuler des séries temporelles