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 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 en savoir plus 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 avec des droits d'administrateur en effectuant un clic droit sur l'icône PowerShell, puis 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.

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.

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.