Ce document explique comment créer des métriques définies par l'utilisateur et écrire ces données de métriques à l'aide de l'API Cloud Monitoring. Les métriques définies par l'utilisateur utilisent les mêmes éléments que les métriques intégrées à Cloud Monitoring:
- Un ensemble de points de données
- Des informations sur les types de métriques, qui vous indiquent ce que les points de données représentent
- Informations sur les ressources surveillées, qui vous indiquent l'origine des points de données
Les métriques définies par l'utilisateur, parfois appelées métriques personnalisées, peuvent être utilisées de la même manière que les métriques intégrées. Autrement dit, vous pouvez créer des graphiques et des alertes pour ces données de métriques.
Les métriques basées sur les journaux sont une classe de métriques définies par l'utilisateur, mais vous ne pouvez pas les créer à l'aide de l'API Cloud Monitoring. Les métriques basées sur les journaux extraient les données de métriques des entrées de journal, mais l'API Monitoring ne fournit aucun moyen de spécifier comment extraire ces données. Utilisez plutôt Cloud Logging pour créer des métriques basées sur les journaux. Lorsque vous créez une métrique basée sur les journaux, Logging crée les structures décrites dans ce document et envoie les données de métriques à Cloud Monitoring pour vous. Pour en savoir plus sur la création de métriques basées sur les journaux, consultez les documents suivants:
Pour instrumenter votre application, nous vous recommandons d'utiliser un framework d'instrumentation Open Source neutre du point du vue du fournisseur, tel qu'OpenTelemetry, plutôt que des API spécifiques aux fournisseurs et aux produits ou des bibliothèques clientes. Pour en savoir plus sur l'instrumentation de votre application, consultez la section Instrumentation et observabilité.
Avant de commencer
Pour en savoir plus sur les structures sous-jacentes à toutes les métriques, consultez la section Métriques, séries temporelles et ressources.
Pour utiliser Cloud Monitoring, vous devez disposer d'un projet Google Cloud pour lequel la facturation est activée. Si nécessaire, procédez comme suit:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Vérifiez que la facturation est activée pour votre projet Google Cloud.
- Vérifiez que l'API Monitoring est activée. Pour en savoir plus, consultez la page Activer l'API Monitoring.
Pour les applications s'exécutant en dehors de Google Cloud, votre projet Google Cloud doit authentifier votre application. En règle générale, vous configurez l'authentification en créant un compte de service pour votre projet et en configurant une variable d'environnement.
Pour les applications que vous exécutez sur une instance Amazon Elastic Compute Cloud (Amazon EC2), créez le compte de service pour le projet de connecteur AWS de l'instance.
Pour en savoir plus sur la création d'un compte de service, consultez la page Premiers pas avec l'authentification.
Créer un type de métrique définie par l'utilisateur
Pour créer une métrique définie par l'utilisateur, vous pouvez soit définir un objet MetricDescriptor
qui spécifie diverses informations sur la métrique, soit écrire des données de métrique. Lorsque vous écrivez des données de métriques, Monitoring crée automatiquement le descripteur de la métrique en fonction de la structure des données que vous fournissez.
Pour en savoir plus sur la conception d'un descripteur de la métrique, consultez la section Descripteurs de métriques pour les métriques définies par l'utilisateur.
Créer automatiquement des descripteurs de métrique
Si vous écrivez des données de métrique alors qu'il n'existe pas encore de descripteur de la métrique définie par l'utilisateur, un descripteur de la métrique est créé automatiquement. Toutefois, ce nouveau descripteur pourrait ne pas ressembler exactement à ce que vous imaginiez. La création automatique de descripteurs de métrique implique certaines hypothèses et certains paramètres par défaut.
Cloud Monitoring crée un objet MetricDescriptor
lorsque l'objet TimeSeries
inclus dans un appel à timeSeries.create
fait référence à un objet Metric
qui spécifie un nom de type de métrique inexistant.
Cloud Monitoring utilise les règles suivantes pour renseigner le champ MetricDescriptor
:
type
: le type est copié à partir du champtype
de l'objetMetric
.name
: le nom est créé à partir de l'ID du projet dans l'appel de méthode et de la valeur detype
dans l'objetMetric
.labels
: libellés qui apparaissent dans l'objetMetric
. Chaque descripteur de libellé du nouveau descripteur de métrique comporte les champs suivants :key
: clé de libellé dans l'objetMetric
valueType
:STRING
description
: non défini
metricKind
: le genre de métrique est défini surGAUGE
, sauf si vous spécifiez le paramètremetricKind
de l'objetTimeSeries
. Lorsque vous spécifiezmetricKind
, la nouvelle métrique est de ce genre. Vous ne pouvez spécifier que les genresGAUGE
etCUMULATIVE
.valueType
: le type de valeur provient de la valeur typée duPoint
en cours d'écriture. Le type de valeur doit êtreBOOL
,INT64
,DOUBLE
ouDISTRIBUTION
. Lorsque vous spécifiez un type de valeur dans le champvalueType
deTimeSeries
, ce type doit correspondre à celui dePoint
.unit
: non définidescription
:"Auto created custom metric."
.displayName
: non défini
Vous pouvez, dans un seul appel timeSeries.create
, inclure plusieurs objets TimeSeries
faisant référence au même type de métrique inexistant. Dans ce cas, les étiquettes du nouveau descripteur de la métrique consistent en l'union de toutes les étiquettes des objets Metric
de toutes les séries temporelles de cet appel à create
.
Étape suivante: consultez Écrire des métriques définies par l'utilisateur.
Créer manuellement des descripteurs de métrique
Pour créer un descripteur de la métrique, procédez comme suit:
Déterminez la structure de votre descripteur de la métrique. Pour vous aider dans ces choix, vous pouvez parcourir les métriques intégrées et consulter leurs données de séries temporelles:
Choisissez un nom de métrique pour votre métrique définie par l'utilisateur.
Choisissez le nom à afficher et la description de votre métrique. Le nom à afficher est utilisé dans la console Google Cloud.
Choisissez un ou plusieurs projets dans lesquels définir votre métrique définie par l'utilisateur et écrire ses données de séries temporelles. Lorsque vous avez besoin de la même métrique dans plusieurs projets, définissez-la à l'identique dans chacun d'eux.
Pour écrire des métriques définies par l'utilisateur à partir de ressources gérées par un compte AWS, créez le descripteur de la métrique dans le projet de connecteur AWS pour ce compte.
Déterminez le type, le type de valeur et (facultatif) les unités de la métrique. Les types de valeurs et les genres de métriques ne sont pas tous compatibles avec les métriques définies par l'utilisateur. Pour en savoir plus sur ces champs, consultez la page Types de valeurs et genres de métriques.
Définissez les libellés de la métrique : noms, types de valeur et descriptions.
Déterminez les ressources surveillées sur lesquelles les données de métriques sont écrites. Faites votre choix dans la liste suivante:
aws_ec2_instance
: instance Amazon EC2.dataflow_job
: job Dataflow.gae_instance
: instance App Engine.gce_instance
: instance Compute Engine.generic_node
: nœud de calcul spécifié par l'utilisateur.generic_task
: tâche définie par l'utilisateur.gke_container
: instance de conteneur GKE.global
: à utiliser lorsqu'aucun autre type de ressource ne convient. Dans la plupart des cas d'utilisation,generic_node
ougeneric_task
sont de meilleurs choix queglobal
.k8s_cluster
: cluster Kubernetes.k8s_container
: conteneur Kubernetes.k8s_node
: nœud Kubernetes.k8s_pod
: pod Kubernetes.
Créez un objet
MetricDescriptor
, puis transmettez-le en tant qu'argument à un appel à la méthodemetricDescriptors.create
.
Appeler metricDescriptors.create
en utilisant le même nom de type qu'un descripteur de la métrique existant renvoie généralement une erreur. Notez qu'une erreur ne survient pas si tous les champs du nouvel objet MetricDescriptor
correspondent exactement aux champs du descripteur existant, mais l'appel n'a alors aucun effet.
Dans l'exemple suivant, vous allez créer une métrique de jauge.
Protocole
Pour créer un descripteur de métrique, utilisez la méthode metricDescriptors.create
.
Vous pouvez exécuter cette méthode à l'aide du widget APIs Explorer sur la page de référence de la méthode. Pour en savoir plus, consultez la page APIs Explorer.
Voici des exemples de paramètres pour metricDescriptors.create
:
- name (URL) :
projects/[PROJECT_ID]
Corps de la requête : fournissez un objet
MetricDescriptor
tel que :{ "name": "", "description": "Daily sales records from all branch stores.", "displayName": "Sales", "type": "custom.googleapis.com/stores/sales", "metricKind": "GAUGE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
Indiquez ces valeurs dans les champs du widget, en utilisant l'ID de votre projet à la place de [PROJECT_ID
] :
Cliquez sur le bouton Execute (Exécuter) pour exécuter la méthode.
Lors de la création d'une métrique, le champ name
de MetricDescriptor
est ignoré et peut être omis. La méthode create
affiche le nouveau descripteur de métrique avec le champ name
renseigné qui, dans cet exemple, se présente comme suit :
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
Si, par exemple, vous souhaitez obtenir le descripteur d'une métrique, utilisez ce nom.
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 Résoudre les problèmes liés aux appels d'API.
Étape suivante: consultez Écrire des métriques définies par l'utilisateur.
Écrire des métriques définies par l'utilisateur
Vous ne pouvez écrire des données que dans des types de métriques pour les métriques définies par l'utilisateur. Pour écrire vos données, utilisez la méthode timeSeries.create
.
Lorsque la série temporelle existe, cette méthode ajoute un nouveau point de données à cette série. Lorsque la série temporelle n'existe pas, cette méthode la crée et ajoute les données.
Vous pouvez écrire des points de données en spécifiant une liste d'objets TimeSeries
avec la méthode timeSeries.create
.
La taille maximale de la liste est de 200 objets, et chacun doit spécifier une série temporelle différente :
- Les valeurs des champs
metric
etresource
identifient un objetTimeSeries
spécifique. Ces champs représentent le type de métrique des données et la ressource surveillée à partir de laquelle les données ont été collectées. - Il est inutile de renseigner les champs
metricKind
etvalueType
, car ils sont ignorés lors de l'écriture des points de données. Chaque objet
TimeSeries
ne doit contenir qu'un seul objetPoint
:- La valeur et l'intervalle de temps spécifiés pour le point doivent être cohérents avec la définition du type de métrique. Pour en savoir plus sur les intervalles de temps correspondant aux différents genres de métriques, consultez la page
TimeInterval
. - L'intervalle de temps du point doit être ultérieur à tout point déjà présent dans la série temporelle.
- L'heure de fin de l'intervalle ne doit pas aller au-delà de 25 heures dans le passé ou de 5 minutes dans le futur.
- La valeur et l'intervalle de temps spécifiés pour le point doivent être cohérents avec la définition du type de métrique. Pour en savoir plus sur les intervalles de temps correspondant aux différents genres de métriques, consultez la page
Pour écrire plusieurs points dans une même série temporelle, appelez la méthode
timeSeries.create
pour chacun d'eux. N'écrivez pas de données dans une série temporelle unique plus rapidement qu'un point pour chaque tranche de 5 secondes. Lorsque vous ajoutez des points de données à différentes séries temporelles, aucune limitation du débit n'est appliquée.
Protocole
Pour écrire des données de métrique, utilisez la méthode timeSeries.create
.
Vous pouvez exécuter cette méthode à l'aide du widget APIs Explorer sur la page de référence de la méthode. Pour en savoir plus, consultez la page APIs Explorer.
Pour écrire un point dans la métrique stores/daily_sales
créée lors de la création manuelle de descripteurs de métrique, procédez comme suit:
- Accédez à la page de référence sur
timeSeries.create
. - Indiquez les paramètres ci-dessous au widget APIs Explorer.
- Cliquez sur le bouton Execute (Exécuter).
Utilisez les exemples de paramètres suivants :
- name :
projects/[PROJECT_ID]
Corps de la requête : inclut une liste d'objets
TimeSeries
. L'exemple suivant ne comporte qu'une seule série temporelle.{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/my_metric", "labels": { "my_label": "my_value" } }, "resource": { "type": "gce_instance", "labels": { "project_id": "[PROJECT_ID]", "instance_id": "1234567890123456789", "zone": "us-central1-f" } }, "points": [ { "interval": { "endTime": "2018-06-01T10:00:00-04:00" }, "value": { "doubleValue": 123.45 } } ] } ] }
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 Résoudre les problèmes liés aux appels d'API.
Supprimer des métriques définies par l'utilisateur
Pour supprimer une métrique définie par l'utilisateur, supprimez son descripteur de la métrique. Vous ne pouvez pas supprimer les données de séries temporelles stockées dans votre projet Google Cloud. Toutefois, la suppression du descripteur de métrique les rend inaccessibles. Les données ont un délai d'expiration et sont supprimées conformément à la règle de conservation des données.
Vous ne pouvez pas supprimer le descripteur d'une métrique intégrée.
Pour supprimer le descripteur de la métrique, appelez la méthode metricDescriptors.delete
.
Protocole
Pour supprimer un descripteur de métrique, utilisez la méthode metricDescriptors.delete
.
Vous pouvez exécuter cette méthode à l'aide du widget APIs Explorer sur la page de référence de la méthode. Pour en savoir plus, consultez la page APIs Explorer.
Pour supprimer la métrique stores/daily_sales
créée dans la section Créer manuellement des descripteurs de métrique, procédez comme suit:
- Accédez à la page de référence sur
metricDescriptors.delete
: Indiquez le nom du descripteur de métrique dans le widget APIs Explorer :
name :
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
Cliquez sur le bouton Execute (Exécuter).
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 Résoudre les problèmes liés aux appels d'API.
Modifier une métrique définie par l'utilisateur
Pour modifier une métrique définie par l'utilisateur, vous devez mettre à jour l'objet MetricDescriptor
qui définit la métrique.
La seule modification acceptée consiste à ajouter des étiquettes.
Pour ajouter des étiquettes à une métrique définie par l'utilisateur existante, utilisez la méthode timeSeries.create
et incluez les nouvelles étiquettes avec les données de séries temporelles. Les étiquettes sont ajoutées au descripteur de métrique lorsque celles que vous tentez d'écrire sont valides et que le nombre total d'étiquettes est inférieur à 30.
Les données de séries temporelles sont ensuite écrites comme si le libellé était présent depuis le début.
Si vous souhaitez aller plus loin que l'ajout de nouveaux libellés, vous devez supprimer et recréer le descripteur de la métrique. Dans ce cas, vous perdez l'ensemble des données de séries temporelles précédemment collectées pour l'ancien descripteur de métrique. Pour en savoir plus, consultez Supprimer des métriques définies par l'utilisateur.
Vous ne pouvez pas renommer une métrique.
Étapes suivantes
- Affichez et gérez l'utilisation des métriques
- Liste des métriques intégrées
- Liste des ressources surveillées