La méthode timeSeries.list de l'API Monitoring vous permet de récupérer, de filtrer et d'agréger des données de séries temporelles brutes ou traitées sur un intervalle de temps spécifié. Vous pouvez appeler timeSeries.list à l'aide d'une bibliothèque cliente spécifique au langage.
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 en savoir plus sur les métriques et les séries temporelles, consultez Métriques, séries temporelles et ressources.
Vous spécifiez les données de série temporelle 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 obtenir 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.typedans le filtre parcustom.googleapis.comou un autre préfixe s'il est utilisé.external.googleapis.comest 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,
labelest correct même si l'objet de métrique réel utiliselabelscomme 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"
Les composants de filtre peuvent être combinés en un seul filtre de série temporelle, comme suit :
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 être utilisée pour renvoyer des données brutes 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 Résoudre les problèmes liés à 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, le résultat de cette requête est d'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 dans l'ordre chronologique inverse. Il n'est pas possible de modifier cet ordre.
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 Résoudre les problèmes liés à l'API Monitoring.
Agrégation des données
La méthode timeSeries.list peut effectuer des agrégations et des réductions 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 des limites exactes de 10 minutes. Les données alignées peuvent ensuite être traitées plus en détail.
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 Résoudre les problèmes liés à 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 Résoudre les problèmes liés à l'API Monitoring.
Étapes suivantes
- En savoir plus sur la conservation et la latence des données de métriques
- Découvrez comment filtrer et agréger des données : manipuler des séries temporelles.