Présentation des métriques définies par l'utilisateur

Les métriques définies par l'utilisateur (également appelées métriques personnalisées) dans Cloud Monitoring vous permettent de capturer des données de télémétrie spécifiques à l'application ou côté client que les métriques Google Cloud intégrées ne collectent pas. Par exemple, vous pouvez enregistrer le nombre de routines d'arrière-plan générées par votre application, puis créer des graphiques, lire et envoyer des alertes sur ces métriques, comme vous le feriez pour les métriques intégrées.

Méthodes de collecte et de lecture des métriques définies par l'utilisateur

Pour instrumenter votre code et collecter des métriques définies par l'utilisateur, nous vous recommandons d'utiliser OpenTelemetry, même si vous pouvez également utiliser Prometheus ou l'API Cloud Monitoring directement. Pour extraire des métriques à partir d'entrées de journal, créez plutôt des métriques basées sur les journaux dans Cloud Logging. Vous pouvez surveiller l'ingestion de vos métriques sur la page Gestion des métriques de la console Google Cloud .

Pour en savoir plus sur la création de métriques définies par l'utilisateur, consultez les documents suivants :

En ce qui concerne Cloud Monitoring, vous pouvez utiliser des métriques définies par l'utilisateur comme les métriques intégrées. Vous pouvez les représenter sous forme de graphique, définir des alertes, les lire et les surveiller. Pour en savoir plus sur la lecture des données de métriques, consultez les documents suivants :

  • La page Répertorier les types de métriques et de ressources explique comment répertorier et examiner vos types de métriques intégrés et définis par l'utilisateur. Par exemple, vous pouvez utiliser les informations de ce document pour lister tous les descripteurs de métriques définis par l'utilisateur dans votre projet.
  • La page Récupérer des données de séries temporelles explique comment récupérer des données de séries temporelles à partir de métriques à l'aide de l'API Monitoring. Par exemple, ce document explique comment utiliser l'API pour obtenir l'utilisation du processeur pour les instances de machine virtuelle (VM) de votre projet Google Cloud .

Descripteurs de métriques pour les métriques définies par l'utilisateur

Chaque type de métrique doit avoir un descripteur de la métrique qui définit l'organisation des données de la métrique. Le descripteur de la métrique définit également les étiquettes de la métrique et le nom de la métrique. Par exemple, les listes de métriques affichent les descripteurs de métriques pour tous les types de métriques intégrés.

Cloud Monitoring peut créer le descripteur de la métrique pour vous, en utilisant les données de métriques que vous écrivez, ou vous pouvez créer explicitement le descripteur de métrique, puis écrire les données de métriques. Dans les deux cas, vous devez décider de la manière dont vous souhaitez organiser vos données de métriques.

Exemple de conception

Supposons que vous disposiez d'un programme qui s'exécute sur une seule machine et que ce programme appelle les programmes auxiliaires A et B. Vous souhaitez compter le nombre de fois où les programmes A et B sont appelés. Vous souhaitez également savoir quand le programme A est appelé plus de 10 fois par minute et quand le programme B est appelé plus de 5 fois par minute. Enfin, supposons que vous disposiez d'un seul projet Google Cloud et que vous prévoyiez d'écrire les données sur la ressource surveillée global.

Cet exemple décrit quelques conceptions différentes que vous pouvez utiliser pour vos métriques définies par l'utilisateur :

  • Vous utilisez deux métriques : Metric-type-A compte les appels au programme A et Metric-type-B compte les appels au programme B. Dans ce cas, Metric-type-A contient une série temporelle et Metric-type-B contient une série temporelle.

    Avec ce modèle de données, vous pouvez créer une seule règle d'alerte avec deux conditions, ou deux règles d'alerte avec une condition chacune. Une règle d'alerte peut accepter plusieurs conditions, mais elle possède une configuration unique pour les canaux de notification.

    Ce modèle peut être approprié lorsque vous n'êtes pas intéressé par des similitudes entre les données des activités surveillées. Dans cet exemple, les activités correspondent au taux d'appels aux programmes A et B.

  • Vous utilisez une seule métrique et une étiquette pour stocker un identifiant de programme. Par exemple, l'étiquette peut stocker la valeur A ou B. Monitoring crée une série temporelle pour chaque combinaison unique d'étiquettes. Par conséquent, il existe une série temporelle dont la valeur d'étiquette est A et une autre série temporelle dont la valeur d'étiquette est B.

    Comme avec le modèle précédent, vous pouvez créer une ou deux règles d'alerte. Cependant, les conditions de la règle d'alerte sont plus complexes. Une condition qui génère une alerte lorsque le taux d'appels pour le programme A dépasse un seuil doit utiliser un filtre qui n'inclut que les points de données dont la valeur d'étiquette est A.

    L'un des avantages de ce modèle est qu'il facilite le calcul des ratios. Par exemple, vous pouvez déterminer la somme totale due aux appels à A.

  • Vous utilisez une seule métrique pour compter le nombre d'appels, mais vous n'utilisez pas d'étiquette pour enregistrer le programme appelé. Dans ce modèle, il existe une seule série temporelle qui combine les données des deux programmes. Toutefois, vous ne pouvez pas créer de règle d'alerte répondant à vos objectifs, car les données des deux programmes ne peuvent pas être séparées.

Les deux premières conceptions vous permettent de répondre à vos exigences d'analyse de données, mais pas la dernière.

Pour en savoir plus, consultez Créer une métrique définie par l'utilisateur.

Noms des métriques définies par l'utilisateur

Lorsque vous créez une métrique définie par l'utilisateur, vous définissez un identifiant de chaîne qui représente le type de métrique. Cette chaîne doit être unique parmi les métriques définies par l'utilisateur dans votre projetGoogle Cloud et doit utiliser un préfixe qui marque la métrique comme étant définie par l'utilisateur. Pour Monitoring, les préfixes autorisés sont custom.googleapis.com/, workload.googleapis.com/, external.googleapis.com/user et external.googleapis.com/prometheus. Le préfixe est suivi d'un nom qui décrit ce que vous collectez. Pour en savoir plus sur la méthode recommandée pour nommer une métrique, consultez Conventions d'attribution de noms aux métriques. Voici des exemples des deux genres d'identifiants employés pour les types de métriques :

    custom.googleapis.com/cpu_utilization
    custom.googleapis.com/instance/cpu/utilization

Dans l'exemple précédent, le préfixe custom.googleapis.com indique que les deux métriques sont définies par l'utilisateur. Les deux exemples concernent des métriques qui mesurent l'utilisation du processeur. Toutefois, ils utilisent des modèles d'organisation différents. Lorsque vous prévoyez d'avoir un grand nombre de métriques définies par l'utilisateur, nous vous recommandons d'utiliser une structure de dénomination hiérarchique comme celle utilisée dans le deuxième exemple.

Tous les types de métriques possèdent des identifiants uniques globaux appelés noms de ressources. La structure d'un nom de ressource pour un type de métrique est la suivante :

projects/PROJECT_ID/metricDescriptors/METRIC_TYPE

où METRIC_TYPE est l'identifiant de chaîne du type de métrique. Si les exemples de métriques précédents sont créés dans le projet my-project-id, les noms de ressources de ces métriques sont les suivants :

    projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
    projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization

Nom ou type ? Dans le descripteur de la métrique, le champ name stocke le nom de ressource du type de métrique et le champ type stocke la chaîne METRIC_TYPE.

Types de ressources surveillées pour les métriques définies par l'utilisateur

Lorsque vous écrivez vos données dans une série temporelle, vous devez indiquer leur origine. Pour spécifier la source des données, vous devez choisir un type de ressource surveillée qui représente l'origine de vos données, puis l'utiliser pour décrire l'origine spécifique. La ressource surveillée ne fait pas partie du type de métrique. À la place, la série temporelle dans laquelle vous écrivez des données inclut une référence au type de métrique et une référence à la ressource surveillée. Le type de métrique décrit les données, tandis que la ressource surveillée décrit l'origine des données.

Tenez compte de la ressource surveillée avant de créer votre descripteur de la métrique. Le type de ressource surveillée que vous utilisez détermine les libellés que vous devez inclure dans le descripteur de la métrique. Par exemple, la ressource de VM Compute Engine contient des libellés pour l'ID du projet, l'ID de l'instance et la zone de l'instance. Par conséquent, si vous prévoyez d'écrire votre métrique sur une ressource de VM Compute Engine, les étiquettes de ressource incluent l'ID d'instance. Vous n'avez donc pas besoin d'étiquette pour l'ID d'instance dans le descripteur de la métrique.

Chacun des points de données de votre métrique doit être associé à un objet de type "ressource surveillée". Les points de différents objets de ressource surveillée sont conservés dans différentes séries temporelles.

Vous devez utiliser l'un des types de ressources surveillées suivants avec les métriques définies par l'utilisateur :

Une pratique courante consiste à utiliser les objets de type "ressource surveillée" représentant les ressources physiques sur lesquelles le code de votre application est exécuté. Cette approche présente plusieurs avantages :

  • Vous obtenez de meilleures performances par rapport à l'utilisation d'un seul type de ressource.
  • Vous évitez les données hors service causées par plusieurs processus écrivant dans la même série temporelle.
  • Vous pouvez regrouper les données de vos métriques définies par l'utilisateur avec d'autres données de métriques provenant des mêmes ressources.

global et ressources génériques

Les types de ressources generic_task et generic_node sont utiles lorsqu'aucun des types de ressources plus spécifiques n'est approprié. Le type generic_task sert à définir des ressources de type "tâche", telles que des applications. Le type generic_node sert à définir des ressources de type "nœud", telles que des machines virtuelles. Les deux types generic_* ont plusieurs libellés communs dont vous pouvez vous servir pour définir des objets de ressource uniques. Cela facilite leur utilisation dans les filtres de métriques pour les agrégations et les réductions.

En revanche, le type de ressource global ne comporte que l'étiquette project_id. Lorsque vous disposez de nombreuses sources de métriques dans un projet, l'utilisation du même objet de ressource global peut entraîner des conflits et l'écrasement de vos données de métriques.

Méthodes d'API compatibles avec les métriques définies par l'utilisateur

Le tableau suivant indique les méthodes de l'API Monitoring qui acceptent les métriques définies par l'utilisateur et celles qui acceptent les métriques intégrées :

Méthode API Monitoring Utiliser avec des
métriques définies par l'utilisateur		 Utilisation avec des
métriques intégrées
monitoredResourceDescriptors.get oui oui
monitoredResourceDescriptors.list oui oui
metricDescriptors.get oui oui
metricDescriptors.list oui oui
timeSeries.list oui oui
timeSeries.create oui
metricDescriptors.create oui
metricDescriptors.delete oui

Limites et latences

Pour connaître les limites liées aux métriques définies par l'utilisateur et à la conservation des données, consultez Quotas et limites.

Pour conserver vos données de métriques au-delà de la période de conservation, vous devez les copier manuellement vers un autre emplacement, tel que Cloud Storage ou BigQuery.

Pour en savoir plus sur les latences associées à l'écriture de données dans des métriques définies par l'utilisateur, consultez Latence des données de métriques.

Étapes suivantes