Utiliser l'agent Ops et le protocole OpenTelemetry (OTLP)

Ce document explique comment utiliser l'agent Ops et le récepteur OTLP (OpenTelemetry Protocol) pour collecter des métriques et des traces définies par l'utilisateur à partir d'applications instrumentées avec OpenTelemetry et exécutées sur Compute Engine.

Ce document est organisé comme suit :

• Présentation décrivant les cas d'utilisation du récepteur OTLP.
• Conditions préalables à l'utilisation du récepteur OTLP.
• Configurer l'agent pour utiliser le récepteur OTLP.
• Utiliser le récepteur pour collecter des métriques. Cette section explique comment interroger vos métriques OpenTelemetry dans Cloud Monitoring.
• Utiliser le récepteur pour collecter les traces. Cette section explique comment autoriser un compte de service à écrire des données dans Cloud Trace.

Présentation de l'utilisation du récepteur OTLP

Le récepteur OLTP de l'agent Ops vous permet d'effectuer les opérations suivantes :

• Instrumenter votre application à l'aide de l'un des SDK propres aux langages de programmation pour OpenTelemetry. Pour en savoir plus sur les langages acceptés, consultez la page Instrumentation d'OpenTelemetry. La combinaison des SDK OpenTelemetry et de l'agent Ops permet d'automatiser les opérations suivantes :
  • Collecter des métriques OTLP à partir de votre application et les envoyer à Cloud Monitoring pour analyse.
  • Collecter les délais de données de trace OTLP à partir de votre application, puis les envoyer à Cloud Trace pour analyse.
• Collecter des traces à partir d'applications tierces compatibles avec OTLP ou dotées de plug-ins compatibles, telles que Nginx. Le récepteur OTLP de l'agent Ops peut collecter ces traces. Pour obtenir un exemple, consultez la section Module OpenTelemetry Nginx.
• Utiliser l'instrumentation personnalisée OpenTelementry.
• Utiliser l'instrumentation automatique OpenTelemetry.

Vous pouvez utiliser le récepteur pour collecter des métriques, des traces ou les deux. Une fois que l'agent Ops a collecté vos métriques, vous pouvez utiliser les fonctionnalités de Cloud Monitoring pour surveiller vos métriques, y compris les graphiques, les tableaux de bord et les règles d'alerte. Si votre application envoie également des données de trace, vous pouvez utiliser Cloud Trace pour les analyser.

Avantages

Avant la disponibilité du plug-in OTLP pour l'agent Ops, les principaux moyens d'instrumenter vos applications pour collecter des métriques et des traces définies par l'utilisateur étaient les suivants :

• Utiliser des bibliothèques clientes qui implémentent l'API Monitoring ou Trace.
• Utiliser les anciennes bibliothèques OpenCensus.

L'utilisation d'OpenTelemetry avec le récepteur OTLP présente plusieurs avantages par rapport à ces méthodes, y compris :

• OpenTelemetry remplace OpenCensus. Le projet OpenCensus est en cours d'archivage. Pour en savoir plus, consultez la page Qu'est-ce qu'OpenTelemetry ?
• L'ingestion est contrôlée au niveau de l'agent. Vous n'avez donc pas besoin de redéployer vos applications si la configuration de l'agent change.
• Vos applications n'ont pas besoin de configurer des identifiants Google Cloud, toutes les autorisations étant gérées au niveau de l'agent.
• Votre code d'application ne contient pas de code de surveillance ou de traçage spécifique à Google Cloud. Vous n'avez pas besoin d'utiliser directement l'API Monitoring ou Trace.
• Votre application envoie des données à l'agent Ops et, si votre application plante, toutes les données collectées par l'agent Ops ne sont pas perdues.

Limites

L'écouteur OTLP exposé par le récepteur de l'agent Ops est compatible avec le transport gRPC. Le protocole HTTP, utilisé principalement pour les clients JavaScript, n'est pas compatible. Pour plus d'informations sur le protocole OpenTelemetry, consultez la page Détails du protocole.

Le récepteur OTLP ne collecte pas les journaux. Vous pouvez collecter des journaux à l'aide de l'agent Ops et d'autres récepteurs, et inclure des informations de journal dans les segments OTLP. Le récepteur OTLP n'est cependant pas compatible avec la collecte directe des journaux. Pour en savoir plus sur la collecte de journaux à l'aide de l'agent Ops, consultez la section Configurations de journalisation.

Prérequis

Pour collecter des métriques et des traces OTLP à l'aide du récepteur OTLP et de l'agent Ops, vous devez installer l'agent Ops version 2.31.0 ou ultérieure.

Dans ce document, nous partons du principe que vous disposez déjà d'une application basée sur OpenTelemetry écrite à l'aide de l'un des SDK OpenTelemetry. Ce document ne couvre pas l'utilisation des SDK OpenTelemetry. Pour plus d'informations sur les SDK et les langages compatibles, consultez la page Instrumentation d'OpenTelemetry.

Configurer l'agent Ops

Pour configurer l'agent Ops de manière à utiliser le récepteur OTLP, procédez comme suit :

1. Modifiez le fichier de configuration utilisateur pour que l'agent Ops inclue le récepteur OTLP.
2. Redémarrez l'Agent Ops.

Les sections suivantes décrivent chaque étape.

Modifier le fichier de configuration utilisateur de l'agent Ops

Ajoutez les éléments de configuration du récepteur OTLP au fichier de configuration utilisateur pour l'agent Ops :

• Pour Linux : /etc/google-cloud-ops-agent/config.yaml
• Pour Windows : C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Pour obtenir des informations générales sur la configuration de l'agent, consultez la page Modèle de configuration.

Le récepteur OTLP introduit la section de configuration combined pour l'agent Ops. Pour utiliser ce récepteur, vous devez configurer des services pour les métriques et les traces, même si vous n'utilisez pas les deux à la fois.

Les sections suivantes décrivent les étapes de configuration du récepteur OTLP.

Ajouter la section de récepteur combined

Placez le récepteur pour les métriques et les traces OTLP dans la section combined. Aucun processeur ou service n'est autorisé dans la section combined. Vous ne devez pas configurer d'autres récepteurs portant le même nom en tant que récepteur dans la section combined. L'exemple suivant utilise otlp comme nom de récepteur.

La configuration minimale de combined pour OTLP se présente comme suit :

combined:
  receivers:
    otlp:
      type: otlp

Le récepteur otlp possède les options de configuration suivantes :

• type : valeur obligatoire. Doit être otlp
• grpc_endpoint : facultatif. Point de terminaison gRPC sur lequel le récepteur OTLP écoute. La valeur par défaut est 0.0.0.0:4317.

• metrics_mode : facultatif. La valeur par défaut est googlemanagedprometheus, ce qui signifie que le récepteur envoie des métriques OTLP en tant que métriques au format Prometheus à l'aide de l'API Prometheus également utilisée par Managed Service pour Prometheus.

  Pour envoyer les métriques en tant que métriques personnalisées Cloud Monitoring à l'aide de l'API Monitoring, définissez l'option metrics_mode sur la valeur googlecloudmonitoring.

  Ce choix affecte la manière dont vos métriques sont ingérées et mesurées pour la facturation. Pour en savoir plus sur les formats de métriques, consultez la section Formats d'ingestion pour les métriques OTLP.

Ajouter des pipelines OTLP à vos services

Le récepteur OTLP peut collecter des métriques et des traces. Vous devez donc définir un service pour les métriques et les traces. Si vous ne souhaitez pas collecter de métriques ni de traces, vous pouvez créer des services vides. Si vous disposez déjà de services avec d'autres pipelines, vous pouvez y ajouter le pipeline OTLP.

Voici les services metrics et traces avec le récepteur OTLP inclus dans les pipelines :

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

Si vous ne souhaitez pas utiliser le service metrics ou traces pour la collecte OTLP, laissez le récepteur OTLP en dehors du pipeline pour le service. Le service doit exister, même s'il n'a pas de pipelines. Si votre application envoie des données d'un certain type et qu'aucun pipeline correspondant n'inclut le récepteur, l'agent Ops supprime les données.

Redémarrer l'agent Ops

Pour appliquer vos modifications de configuration, vous devez redémarrer l'agent Ops.

Linux

1. Pour redémarrer l'agent, exécutez la commande suivante sur votre instance :

   sudo systemctl restart google-cloud-ops-agent
   

2. Pour vérifier que l'agent a redémarré, exécutez la commande suivante et vérifiez que les composants "Agent de métriques" et "Agent de journalisation" ont démarré :

   sudo systemctl status "google-cloud-ops-agent*"
   

Windows

1. Connectez-vous à votre instance via RDP ou un outil similaire, et connectez-vous à Windows.
2. Ouvrez un terminal PowerShell disposant de droits d'administrateur en effectuant un clic droit sur l'icône PowerShell et en sélectionnant Exécuter en tant qu'administrateur.
3. Pour redémarrer l'agent, exécutez la commande PowerShell suivante :

   Restart-Service google-cloud-ops-agent -Force
   

4. Pour vérifier que l'agent a redémarré, exécutez la commande suivante et vérifiez que les composants "Agent de métriques" et "Agent de journalisation" ont démarré :

   Get-Service google-cloud-ops-agent*
   

Collecter les métriques OTLP

Lorsque vous utilisez le récepteur OTLP pour collecter des métriques à partir de vos applications OpenTelemetry, le choix de configuration principal du récepteur est l'API que vous souhaitez utiliser pour ingérer les métriques.

Pour ce faire, modifiez l'option metrics_mode dans la configuration du récepteur otlp ou utilisez la valeur par défaut. Ce choix affecte la manière dont vos métriques OTLP sont ingérées dans Cloud Monitoring et mesurées pour la facturation.

Remarque : Le nombre et la cardinalité des métriques émises par votre application sont sous votre contrôle. Il n'existe pas d'ensemble organisé de métriques. La quantité de données que vous ingérez est déterminée par votre application.

Le choix de metrics_mode n'affecte pas votre capacité à créer des graphiques, des tableaux de bord et des règles d'alerte dans Monitoring.

• Pour en savoir plus sur la création de graphiques et de tableaux de bord, consultez la page Présentation des tableaux de bord et des graphiques.
• Pour en savoir plus sur les règles d'alerte, consultez la page Présentation des alertes.

Les sections suivantes décrivent les différences de formats utilisés par les modes de métriques et comment interroger les données ingérées pour les utiliser dans Monitoring.

Formats d'ingestion pour les métriques OTLP

Le récepteur OTLP fournit l'option metrics_mode, qui spécifie l'API utilisée pour ingérer vos données de métriques. Par défaut, le récepteur utilise l'API Prometheus. La valeur par défaut de l'option metrics_mode est googlemanagedprometheus. Les métriques sont ingérées à l'aide de la même API que celle utilisée par Managed Service pour Prometheus.

Vous pouvez configurer le récepteur pour envoyer vos données de métriques à l'API Cloud Monitoring à la place. Pour envoyer des données à l'API Monitoring, définissez la valeur de l'option metrics_mode sur googlecloudmonitoring, comme indiqué dans l'exemple suivant :

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

Le format d'ingestion que vous utilisez détermine le mappage des métriques OTLP dans Cloud Monitoring. Vous pouvez créer des graphiques, des tableaux de bord et des règles d'alerte dans Monitoring pour les métriques de n'importe quel format de métrique, mais vous faites référence aux métriques différemment dans les requêtes.

Le format d'ingestion détermine également le modèle de tarification utilisé pour l'ingestion de données.

Les sections suivantes décrivent la tarification, les différences structurelles entre une métrique ingérée par l'API Prometheus et la même métrique ingérée par l'API Monitoring, et expliquent comment y faire référence.

Tarifs et quotas

Le format d'ingestion que vous utilisez détermine le mode de facturation des métriques OTLP :

• API Prometheus : lorsque vous utilisez l'API Prometheus pour ingérer les métriques de votre application, les données sont soumises à une tarification basée sur des échantillons, comme si les métriques étaient transmises à Managed Service pour Prometheus.

  • Pour connaître les tarifs actuels, consultez la page Synthèse des tarifs de Cloud Monitoring.
  • Pour en savoir plus sur le comptage des échantillons et l'estimation des coûts, consultez la section Exemples de tarification basés sur les échantillons ingérés.

• API Monitoring : lorsque vous utilisez l'API Monitoring pour ingérer les métriques de votre application, les données sont soumises à une tarification basée sur le volume, telle que les données d'autres intégrations avec l'agent Ops.

  • Pour connaître les tarifs actuels, consultez la page Synthèse des tarifs de Cloud Monitoring.
  • Pour plus d'informations sur le volume d'ingestion et l'estimation des coûts, consultez la page Exemples de tarification basés sur les octets ingérés.

Les métriques ingérées à l'aide du récepteur OTLP sont considérées comme des types de métriques "personnalisées" lorsqu'elles sont ingérées dans Cloud Monitoring et sont soumises aux quotas et limites des métriques personnalisées.

Structure des métriques

Cloud Monitoring décrit le format des données de métriques à l'aide d'un schéma appelé descripteur de la métrique. Le descripteur de la métrique inclut le nom de la métrique, le type de données des valeurs de la métrique, la relation entre chaque valeur et les valeurs précédentes, ainsi que les libellés associés aux valeurs. Si vous configurez le récepteur OTLP pour ingérer des métriques à l'aide de l'API Prometheus, le descripteur de la métrique créé diffère du descripteur de métrique créé lorsque vous utilisez l'API Monitoring.

API Prometheus : lorsque vous utilisez l'API Prometheus pour ingérer les métriques de votre application, chaque métrique est transformée à l'aide de la norme Transformation OpenTelemetry-to-Prometheus et mappée à un type de ressource surveillée de Cloud Monitoring.

• La transformation inclut les modifications suivantes :
  • Le nom de la métrique OTLP est précédé de la chaîne prometheus.googleapis.com/.
  • Tous les caractères non alphanumériques, tels que les points (.), dans le nom de la métrique OTLP sont remplacés par des traits de soulignement (_).
  • Le nom de la métrique OTLP est précédé d'une chaîne indiquant le genre de métrique, tel que /gauge ou /counter.
• Les libellés suivants, renseignés avec les valeurs de la ressource OTLP, sont ajoutés à la métrique :
  • instance_name : valeur de l'attribut de ressource host.name.
  • machine_type : valeur de l'attribut de ressource host.type.

• La ressource surveillée enregistrée avec les mesures de métriques est le type générique prometheus_target. La série temporelle Prometheus générée inclut les libellés suivants de la ressource prometheus_target, renseignés avec des valeurs de la ressource OTLP :

  • location : valeur de l'attribut de ressource cloud.availability_zone.
  • namespace : valeur de l'attribut de ressource host.id.

  Le type de ressource prometheus_target inclut également les libellés suivants :

  • project_id : identifiant du projet Google Cloud, tel que my-project, dans lequel l'agent Ops s'exécute.
  • cluster : la valeur est toujours __gce__ lorsque les métriques sont collectées par l'agent Ops.

Si les attributs de ressources utilisés pour les valeurs de libellé ne figurent pas dans les données OTLP entrantes, ces valeurs proviennent d'informations sur la VM qui exécute l'agent Ops. Ce comportement signifie que les données OTLP sans ces attributs de ressources apparaissent avec les mêmes libellés que les données collectées par le récepteur Prometheus de l'agent Ops.

API Monitoring : lorsque vous utilisez l'API Monitoring pour ingérer les métriques de votre application, chaque métrique est gérée comme suit :

• Le nom de la métrique OTLP est précédé de la chaîne workload.googleapis.com/, sauf si le nom de la métrique OTLP contient déjà cette chaîne ou un autre domaine de métrique valide, tel que custom.googleapis.com. Nous vous recommandons d'utiliser le domaine "workload".
• La ressource surveillée enregistrée avec les mesures de métriques est le type de machine virtuelle Compute Engine gce_instance.

Les exemples suivants montrent les descripteurs de métrique pour une paire de métriques OpenTelemetry. Les métriques sont créées par une application qui utilise la bibliothèque de métriques OpenTelemetry pour Go. L'onglet API Prometheus affiche le descripteur de métrique créé lorsque le récepteur OTLP utilise le mode de métriques Prometheus par défaut. L'onglet API Monitoring affiche le descripteur de métrique créé lorsque le récepteur OTLP utilise le mode de métrique googlecloudmonitoring.

Aucune modification n'est apportée à l'application qui crée la métrique. Le mode de métrique utilisé par le récepteur OTLP est la seule différence.

L'application crée une métrique de jauge OTLP, otlp.test.gauge, qui enregistre des valeurs à virgule flottante 64 bits. Les onglets suivants affichent le descripteur de métrique créé par chaque API d'ingestion :

API Prometheus

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

API Monitoring

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

L'application crée une métrique de compteur OTLP, otlp.test.cumulative, qui enregistre des valeurs à virgule flottante 64 bits croissantes. Les onglets suivants affichent le descripteur de métrique créé par chaque API d'ingestion :

API Prometheus

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

API Monitoring

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

Le tableau suivant récapitule certaines des différences de format imposées par les API utilisées pour ingérer des métriques OTLP :

	API Prometheus	API Monitoring
Domaine de métriques	prometheus.googleapis.com	workload.googleapis.com
Nom de la métrique OTLP	Modifié lors de l'ingestion	Utilisé tel que fourni
Ressource surveillée	prometheus_target	gce_instance

Formats d'ingestion et requêtes

Le mode de métriques utilisé dans le récepteur OTLP affecte la manière dont vous interrogez les métriques obtenues dans Cloud Monitoring lorsque vous créez des graphiques, des tableaux de bord et des règles d'alerte.

Lorsque vous configurez un graphique, un tableau de bord ou une règle d'alerte dans Cloud Monitoring, la configuration inclut une requête pour les données sur lesquelles le graphique, le tableau de bord ou la règle d'alerte fonctionne.

Cloud Monitoring accepte les outils suivants pour interroger les données de métriques :

• Une interface basée sur le générateur de requêtes intégrée aux outils tels que l'explorateur de métriques, l'interface du générateur de tableaux de bord et l'interface de configuration des règles d'alerte.
• Langage MQL (Monitoring Query Language) : langage de requête textuel spécifique à Cloud Monitoring.
• Langage Prometheus Query (PromQL) : langage de requête basé sur le texte utilisé par Prometheus Open Source.

Pour en savoir plus sur l'interrogation des métriques OTLP à l'aide de ces outils, consultez les sections suivantes :

• Interroger les métriques OTLP ingérées à l'aide de l'API Prometheus
• Interroger les métriques OTLP ingérées à l'aide de l'API Monitoring

Interroger les métriques OTLP ingérées à l'aide de l'API Prometheus

Cette section explique comment interroger des métriques OTLP ingérées à l'aide de l'API Prometheus, qui est le mode de métrique par défaut pour le récepteur OTLP.

Les requêtes sont basées sur les métriques OTLP décrites dans la section Structure des métriques :

• otlp.test.gauge : métrique de jauge OTLP qui enregistre les valeurs à virgule flottante 64 bits.
• otlp.test.cumlative : métrique de compteur OTLP qui enregistre l'augmentation des valeurs à virgule flottante 64 bits.

Ces métriques sont ingérées dans Cloud Monitoring avec les types de métriques suivants, qui fonctionnent comme des noms :

• prometheus.googleapis.com/otlp_test_gauge/gauge
• prometheus.googleapis.com/otlp_test_cumulative/counter

Les métriques ingérées à l'aide de l'API Prometheus sont écrites par rapport au type de ressource surveillée prometheus_target.

Les onglets présentent les requêtes de base lors de l'interrogation des métriques à l'aide de la console Google Cloud. Ces exemples utilisent l'explorateur de métriques, mais les principes sont les mêmes pour les tableaux de bord et les règles d'alerte.

Interface du générateur de requêtes

Pour interroger les données de métriques à l'aide d'une interface de création de requêtes, vous devez spécifier le type de métrique et le type de ressource surveillée en effectuant la saisie dans les champs pour lesquels la recherche est activée. Il existe beaucoup moins de types de ressources que de types de métriques. Il est donc plus efficace de rechercher le type de ressource, puis d'utiliser le menu des métriques associées pour trouver le type de métrique.

Si vous saisissez "prometheus" dans le champ de recherche, les résultats incluent la ressource surveillée prometheus_target, indiquée par le nom à afficher "Prometheus Target", et la série de métriques qui écrivent dans la ressource. Les métriques sont classées par nom. Les deux exemples de métriques apparaissent sous la catégorie Otlp. Vous pouvez sélectionner Prometheus/otlp_test_cumulative/counter ou Prometheus/otlp_test_gauge/gauge.

Pour plus d'informations sur l'utilisation du générateur de requêtes, consultez la page Créer des requêtes à l'aide de menus.

La capture d'écran suivante montre le résultat de l'interrogation de la métrique prometheus.googleapis.com/otlp_test_gauge/gauge :

La capture d'écran suivante montre le résultat de l'interrogation de la métrique prometheus.googleapis.com/otlp_test_cumulative/counter :

MQL

Pour interroger des données de métriques à l'aide de MQL, utilisez une instruction fetch et spécifiez le type de métrique et le type de ressource surveillée, séparés par le signe ::. Les requêtes MQL triviales pour les métriques d'exemple se présentent comme suit :

• fetch prometheus.googleapis.com/otlp_test_gauge/gauge::prometheus_target
• fetch prometheus.googleapis.com/otlp_test_cumulative/counter::prometheus_target

Pour en savoir plus sur la création de requêtes MQL, consultez la section Exemples de requêtes MQL.

La capture d'écran suivante montre le résultat de l'interrogation de la métrique prometheus.googleapis.com/otlp_test_gauge/gauge :

La capture d'écran suivante montre le résultat de l'interrogation de la métrique prometheus.googleapis.com/otlp_test_cumulative/counter :

PromQL

Lorsque vous utilisez PromQL pour interroger des données de métriques ingérées à l'aide de l'API Prometheus, il vous suffit de spécifier la forme modifiée du nom de la métrique OTLP d'origine. Vous n'avez pas besoin de spécifier la chaîne prometheus.googleapis.com/ en préfixe ni le type en suffixe.

Lorsque la métrique ne peut être écrite que sur un seul type de ressource surveillée, vous n'avez pas besoin de spécifier la ressource. Comme décrit dans la section Structure de métriques, les métriques OTLP ingérées à l'aide de l'API Prometheus ne sont écrites que par rapport au type de ressource surveillée prometheus_target. Les requêtes PromQL triviales pour les exemples de métriques se présentent comme suit :

• otlp_test_gauge
• otlp_test_cumulative

Pour en savoir plus sur l'utilisation de PromQL dans Cloud Monitoring pour interroger les métriques ingérées à l'aide de l'API Prometheus, consultez la page Données Google Cloud Managed Service pour Prometheus dans Cloud Monitoring. Pour en savoir plus sur le langage PromQL, consultez la page Interroger des métriques Prometheus.

La capture d'écran suivante montre le résultat de l'interrogation de la métrique prometheus.googleapis.com/otlp_test_gauge/gauge :

La capture d'écran suivante montre le résultat de l'interrogation de la métrique prometheus.googleapis.com/otlp_test_cumulative/counter :

Interroger les métriques OTLP ingérées à l'aide de l'API Monitoring

Cette section explique comment interroger des métriques OTLP ingérées à l'aide de l'API Monitoring. Pour sélectionner l'API Cloud Monitoring, définissez le champ metrics_mode du récepteur OTLP sur la valeur googlecloudmonitoring.

Les requêtes sont basées sur les métriques OTLP décrites dans la section Structure des métriques :

• otlp.test.gauge : métrique de jauge OTLP qui enregistre les valeurs à virgule flottante 64 bits.
• otlp.test.cumlative : métrique de compteur OTLP qui enregistre l'augmentation des valeurs à virgule flottante 64 bits.

Ces métriques sont ingérées dans Cloud Monitoring avec les types de métriques suivants, qui fonctionnent comme des noms :

• workload.googleapis.com/otlp.test.gauge
• workload.googleapis.com/otlp.test.cumulative

Les métriques ingérées à l'aide de l'API Monitoring sont écrites par rapport au type de ressource surveillée gce_instance.

Les onglets présentent les requêtes de base lors de l'interrogation des métriques à l'aide de la console Google Cloud. Ces exemples utilisent l'explorateur de métriques, mais les principes sont les mêmes pour les tableaux de bord et les règles d'alerte.

Interface du générateur de requêtes

Pour interroger les données de métriques à l'aide d'une interface de création de requêtes, vous devez spécifier le type de métrique et le type de ressource surveillée en effectuant la saisie dans les champs pour lesquels la recherche est activée. Il existe beaucoup moins de types de ressources que de types de métriques. Il est donc plus efficace de rechercher le type de ressource, puis d'utiliser le menu des métriques associées pour trouver le type de métrique.

Si vous saisissez "gce_instance" dans le champ de recherche, les résultats affichent le type de ressource par son nom à afficher, "Instance de VM", ainsi que l'ensemble de métriques qui écrivent dans la ressource. Les métriques sont classées par nom. Les deux exemples de métriques apparaissent en tant que catégorie Otlp. Vous pouvez sélectionner Workload/otlp_test_cumulative ou Workload/otlp_test_gauge.

Pour plus d'informations sur l'utilisation du générateur de requêtes, consultez la page Créer des requêtes à l'aide de menus.

La capture d'écran suivante montre le résultat de l'interrogation de la métrique workload.googleapis.com/otlp.test.gauge :

La capture d'écran suivante montre le résultat de l'interrogation de la métrique workload.googleapis.com/otlp.test.cumulative :

MQL

Pour interroger des données de métriques à l'aide de MQL, utilisez une instruction fetch et spécifiez le type de métrique et le type de ressource surveillée, séparés par le signe ::. Les requêtes MQL triviales pour les métriques d'exemple se présentent comme suit :

• fetch workload.googleapis.com/otlp.test.gauge::gce_instance
• fetch workload.googleapis.com/otlp.test.cumulative::gce_instance

Pour en savoir plus sur la création de requêtes MQL, consultez la section Exemples de requêtes MQL.

La capture d'écran suivante montre le résultat de l'interrogation de la métrique workload.googleapis.com/otlp.test.gauge :

La capture d'écran suivante montre le résultat de l'interrogation de la métrique workload.googleapis.com/otlp.test.cumulative :

PromQL

Lorsque vous utilisez PromQL pour interroger des données de métriques ingérées à l'aide de l'API Monitoring, vous devez mapper le nom de la métrique aux conventions PromQL. Les règles de mappage de base sont les suivantes :

• Remplacez la première expression / par :.
• Remplacez tous les autres caractères spéciaux (y compris . et d'autres caractères /) par _.

Pour plus d'informations sur les règles de mappage, consultez la section Mapper des métriques Cloud Monitoring à PromQL.

Les types de métriques Monitoring pour les exemples de métriques sont mappés sur PromQL comme suit :

• workload_googleapis_com:otlp_test_gauge
• workload_googleapis_com:otlp_test_cumulative

Lorsque la métrique ne peut être écrite que sur un seul type de ressource surveillée, vous n'avez pas besoin de spécifier la ressource. Les exemples de métriques sont écrits par rapport au type de ressource surveillée gce_instance, mais comme décrit dans la section Structure des métriques, gce_instance n'est qu'un des types de métriques possibles. Par conséquent, les requêtes PromQL pour ces métriques doivent inclure un filtre pour le type de ressource gce_instance. Pour inclure le filtre, ajoutez la chaîne suivante à la fin des noms de métriques mappées : {monitored_resource="gce_instance"}

Pour plus d'informations sur l'utilisation de PromQL dans Cloud Monitoring, consultez la page PromQL dans Cloud Monitoring. Pour en savoir plus sur le langage PromQL, consultez la page Interroger des métriques Prometheus.

Les requêtes PromQL triviales pour les exemples de métriques se présentent comme suit :

• workload_googleapis_com:otlp_test_gauge{monitored_resource="gce_instance"}
• workload_googleapis_com:otlp_test_cumulative{monitored_resource="gce_instance"}

La capture d'écran suivante montre le résultat de l'interrogation de la métrique workload.googleapis.com/otlp.test.gauge :

La capture d'écran suivante montre le résultat de l'interrogation de la métrique workload.googleapis.com/otlp.test.cumulative :

Afficher les données d'utilisation et de diagnostic des métriques dans Cloud Monitoring

La page Gestion des métriques de Cloud Monitoring fournit des informations qui peuvent vous aider à contrôler les sommes que vous consacrez aux métriques facturables, sans affecter l'observabilité. La page Gestion des métriques fournit les informations suivantes :

• Les volumes d'ingestion pour la facturation à base d'octets et celle à base d'exemples, englobant les différents domaines de métriques et des métriques individuelles
• Les données sur les libellés et la cardinalité des métriques
• L'utilisation de métriques dans les règles d'alerte et les tableaux de bord personnalisés
• Les taux d'erreurs d'écriture de métriques

Procédez comme suit pour afficher la page Gestion des métriques :

1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Monitoring, puis  Gestion des métriques :

   Accéder à Gestion des métriques

2. Dans la barre d'outils, sélectionnez votre période. Par défaut, la page Gestion des métriques affiche des informations sur les métriques collectées au cours du jour précédent.

Pour en savoir plus sur la page Gestion des métriques, consultez la section Afficher et gérer l'utilisation des métriques.

Collecter les traces OTLP

Si vous avez configuré l'agent Ops pour collecter des traces, mais que vous n'obtenez aucune trace dans Cloud Trace lorsque vous exécutez votre application, vous devrez peut-être attribuer un rôle supplémentaire au compte de service Compute Engine utilisé par l'agent. Par défaut, ce compte de service obtient les rôles nécessaires pour écrire des métriques et des journaux, mais pas des traces.

Cette section explique comment accorder au compte de service l'autorisation Cloud Trace nécessaire.

Déterminer les rôles attribués au compte de service

Pour afficher les rôles attribués à un compte de service, exécutez la commande gcloud projects get-iam-policy suivante :

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Vous devriez obtenir une sortie semblable à celle-ci :

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

Si le résultat inclut roles/cloudtrace.agent ou roles/cloudtrace.admin, le compte de service dispose d'autorisations suffisantes pour écrire des traces. Pour attribuer l'un de ces rôles au compte de service, consultez la section suivante.

Attribuer le rôle Cloud Trace au compte de service

Pour un compte de service, le rôle Agent Cloud Trace, roles/cloudtrace.agent, est généralement approprié. Pour accorder ce rôle au compte de service, exécutez la commande gcloud projects add-iam-policy-binding suivante :

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

Vous pouvez ensuite exécuter la commande gcloud projects get-iam-policy pour vérifier que la modification a été effectuée :

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Le résultat inclut maintenant roles/cloudtrace.agent :

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

Pour en savoir plus sur la gestion des rôles IAM, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Une fois que vous avez autorisé le compte de service utilisé par l'agent Ops pour écrire des données dans Cloud Trace, lorsque vous exécutez votre application basée sur OpenTelemetry, les traces apparaissent dans Cloud Trace :

Désactiver le récepteur OTLP

Si vous collectez des métriques et des traces OTLP en utilisant l'agent Ops et que vous souhaitez désactiver la collecte des métriques ou des traces, mais pas les deux, procédez comme suit :

1. Désactivez la collecte de métriques ou de traces en apportant l'une des modifications suivantes au fichier de configuration de l'utilisateur, config.yaml :

   • Supprimez le pipeline otlp du service metrics.
   • Supprimez le pipeline otlp du service traces.

2. Redémarrez l'Agent Ops.

Pour désactiver la collecte de métriques et de traces OTLP par l'agent Ops, procédez comme suit :

1. Supprimez la configuration OTLP du fichier de configuration utilisateur :

   • Supprimez l'intégralité de la section combined, qui inclut le récepteur otlp.
   • Supprimez le pipeline otlp du service metrics.
   • Supprimez l'intégralité du service traces.

2. Redémarrez l'Agent Ops.

Étapes suivantes

Une fois les métriques et les traces de votre application ingérées, vous pouvez utiliser la console Google Cloud pour surveiller et analyser vos données.

• Pour en savoir plus sur les tableaux de bord et les types de graphiques que vous pouvez utiliser, consultez la section Tableaux de bord et graphiques.
• Pour en savoir plus sur les règles d'alerte, consultez la section Utiliser des règles d'alerte.
• Pour en savoir plus sur l'analyse des données de trace, consultez Rechercher et explorer des traces.