Migrer les collecteurs pour utiliser les exportateurs OTLP

L'API Telemetry (OTLP) est une implémentation du protocole OpenTelemetry. La prise en charge d'OTLP vous permet d'ajouter des exportateurs génériques otlphttp et otlp_grpc/otlp_logs à la configuration de votre collecteur, en évitant les exportateurs spécifiques à un fournisseur. Les applications peuvent envoyer des données de journal, de métriques et de traces à l'API Telemetry.

Ce guide s'applique à vous si la configuration de votre collecteur utilise l' googlecloud exportateur ou l' googlemanagedprometheus exportateur :

Pour migrer vers les exportateurs OTLP, procédez comme suit :

  1. Activer l'API Telemetry
  2. Autoriser le compte de service du collecteur
  3. Définir la variable d'environnement GOOGLE_CLOUD_PROJECT
  4. Ajouter l'extension googleclientauth
  5. Ajouter les exportateurs otlphttp et otlp_grpc/otlp_logs
  6. Ajouter des processeurs
  7. Mettre à jour les pipelines de service
  8. Valider votre configuration
  9. Migrer les tableaux de bord et les règles d'alerte
  10. Supprimer les exportateurs spécifiques à un fournisseur

Activer l'API Telemetry

Les exportateurs OTLP écrivent dans l'API Telemetry. Vous devez donc activer cette API dans votre projet. Pour activer l'API Telemetry, exécutez la commande suivante :

gcloud services enable telemetry.googleapis.com

Autoriser le compte de service du collecteur

Le collecteur s'authentifie auprès des Google Cloud API à l'aide de l'identité de l' environnement dans lequel il s'exécute. Le compte de service qui exécute votre collecteur doit être autorisé à utiliser l'API Telemetry pour écrire des données de journal, de métriques et de traces. De plus, comme l'API Telemetry est une API consommateur, vous devez spécifier explicitement le Google Cloud projet dont le quota est consommé par les appels d'API et accorder au compte de service les autorisations nécessaires pour consommer le quota de ce projet.

Rôles requis

Pour vous assurer que le compte de service qui exécute votre collecteur dispose des autorisations nécessaires pour envoyer des données de journal, de métriques et de traces, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service qui exécute votre collecteur sur votre projet :

Ces rôles prédéfinis contiennent les autorisations requises pour envoyer des données de journal, de métriques et de traces. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour envoyer des données de journal, de métriques et de traces :

  • logging.logEntries.create
  • monitoring.timeSeries.create
  • telemetry.traces.write
  • serviceusage.services.use

Compte de service Kubernetes

Si vous déployez le collecteur sur Google Kubernetes Engine (GKE) à l'aide de Workload Identity Federation for GKE, accordez les rôles requis à votre compte de service Kubernetes.

Vous pouvez utiliser les commandes suivantes pour accorder les rôles requis si votre quota d'API est extrait du même Google Cloud projet que celui qui est la destination des appels d'API Telemetry. Avant d'exécuter les commandes, remplacez PROJECT_ID par l' ID de votre projet. Toutefois, si vous utilisez un projet de quota distinct, remplacez PROJECT_ID dans la deuxième commande par l'ID de votre projet de quota :

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/telemetry.writer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/serviceusage.serviceUsageConsumer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Compte de service pour Workload Identity Federation for GKE

Si vous avez configuré un compte de service pour Workload Identity Federation for GKE, vous pouvez utiliser la commande de la documentation Google Cloud Managed Service pour Prometheus pour autoriser le compte de service, en apportant les modifications suivantes :

  • Remplacez gmp-test-sa par le nom de votre compte de service.
  • Exécutez la commande pour accorder les rôles requis afin d'écrire des données de journal, de métriques et de traces.

Autre compte de service

Si vous exécutez le collecteur sur une VM Compute Engine ou en dehors de GKE, accordez les rôles requis au Google Cloud compte de service utilisé par votre déploiement.

Définir la variable d'environnement GOOGLE_CLOUD_PROJECT

Définissez la variable d'environnement GOOGLE_CLOUD_PROJECT dans le déploiement de votre collecteur. Le résultat ressemble à ceci :

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

Ajouter l'extension googleclientauth

Ajoutez l'extension googleclientauth à la configuration de votre collecteur. L'API Telemetry est une API consommateur et nécessite que vous spécifiiez à la fois votre Google Cloud projet et votre projet de quota. Le résultat doit ressembler à ce qui suit :

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

Ajouter les exportateurs otlphttp et otlp_grpc/otlp_logs

Utilisez l'exportateur otlphttp pour envoyer des données de métriques et de traces au format OTLP à votre projet, et l'exportateur otlp_grpc/otlp_logs pour envoyer des données de journal. Veillez à configurer les deux exportateurs avec l'extension googleclientauth.

Le résultat doit ressembler à ce qui suit :

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

Pour l'exportateur otlp_grpc/otlp_logs, le champ endpoint doit être spécifié au format host:port.

Ajouter des processeurs

Cette section liste les processeurs que vous devez ajouter à votre collecteur. Vous pouvez également utiliser d'autres processeurs. Par exemple, les configurations de collecteur Google-Built OpenTelemetry Collector incluent généralement le processeur memory_limiter et un processeur qui transforme les données de métriques. Pour obtenir un exemple, consultez Google-Built OpenTelemetry Collector sur GKE.

Ajouter le processeur resource/gcp_project_id

Ajoutez un processeur resource qui capture des informations sur votre Google Cloud projet.

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

Ajouter le processeur resourcedetection

Si vous exécutez sur Google Cloud, envisagez d'ajouter le resourcedetection processeur. Ce processeur peut découvrir automatiquement des informations sur votre architecture.

La configuration suivante recherche les variables d'environnement OpenTelemetry standards, puis interroge le Google Cloud serveur de métadonnées pour collecter des informations sur votre infrastructure :

  resourcedetection:
    detectors: ["env", "gcp"]

Ajouter le processeur batch

Pour envoyer plus efficacement votre télémétrie à votre Google Cloud projet, nous vous recommandons d'utiliser le batch processeur.

Par exemple, le collecteur Google-Built OpenTelemetry Collector utilise la configuration suivante pour le processeur de lot :

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

Ajouter le processeur metricstarttime

Ajoutez le processeur metricstarttime à la configuration. Ce processeur s'assure que les métriques cumulatives incluent à la fois une heure de début et une heure d'observation. Par défaut, les métriques Prometheus n'incluent qu'une heure actuelle. Par conséquent, si vous omettez ce processeur et que votre application génère des métriques Prometheus, vos données de métriques peuvent être rejetées ou vous pouvez constater des pics de données.

Vous devez ajouter ce processeur si votre collecteur reçoit des métriques Prometheus.

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

Ajouter le processeur de transformation

Pour conserver la source et la version de l'instrumentation dans vos données de journal, ajoutez le processeur transform suivant :

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

Mettre à jour les pipelines de service

Ensuite, mettez à jour les pipelines de votre collecteur pour utiliser les exportateurs otlp_grpc/otlp_logs et otlphttp. Pour les données de journal et de trace, ces instructions remplacent votre exportateur actuel par l'exportateur OTLP approprié. Pour vos données de métriques, ces instructions entraînent une double écriture. Cette approche vous permet de vérifier que l'exportateur OTLP est envoie des données de métriques à votre Google Cloud projet. Elle vous permet également de mettre à jour les graphiques et les règles d'alerte avant de désactiver les flux de données de l'exportateur d'origine.

Apportez les modifications suivantes aux configurations de pipeline de votre collecteur :

  1. Ajoutez l'extension googleclientauth à l'entrée service.

  2. Pour votre pipeline de journaux, remplacez googlecloud/logging par otlp_grpc/otlp_logs, puis ajoutez les processeurs suivants à la liste des processeurs du pipeline :

    • resource/gcp_project_id
    • transform/otlp_grpc/preserve_instrumentation_source_version
    • resourcedetection (si vous avez ajouté ce processeur)
    • batch

    Cette configuration effectue une seule écriture des données de journal. Si vous souhaitez écrire vos données de journal deux fois, ajoutez l'exportateur otlp_grpc/otlp_logs à la liste des exportateurs.

  3. Pour votre pipeline de métriques, ajoutez l'exportateur otlphttp à la liste des exportateurs du pipeline à côté de l'exportateur googlemanagedprometheus, puis ajoutez les processeurs suivants :

    • resource/gcp_project_id
    • metricstarttime
    • resourcedetection (si vous avez ajouté ce processeur)
    • batch

    Cette configuration effectue une double écriture des données de métriques. Une fois que vous avez validé le flux de données de métriques et mis à jour les graphiques et les règles d'alerte, supprimez l'exportateur Prometheus.

  4. Pour votre pipeline de traces, remplacez votre exportateur actuel par l'exportateur otlphttp, puis ajoutez les processeurs suivants :

    • resource/gcp_project_id
    • resourcedetection (si vous avez ajouté ce processeur)
    • batch

    Cette configuration effectue une seule écriture des données de trace.

Le résultat de ces modifications est semblable à ce qui suit :

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

L'extrait précédent utilise le récepteur OTLP pour vos données de journal, de métriques et de traces. La configuration de votre collecteur peut être différente. Par exemple, si vous disposez d'une application qui écrit des données de journal structurées, le récepteur filelog est approprié.

Valider votre configuration

Redémarrez votre déploiement, puis vérifiez que vos otlphttp et otlp_grpc/otlp_logs exportateurs envoient des données à votre Google Cloud projet. Pour vérifier votre configuration, procédez comme suit :

  • Interrogez vos entrées de journal pour détecter les erreurs liées à l'écriture de données de télémétrie.
  • Affichez les taux d'erreur pour l'API Cloud Logging, l'API Cloud Monitoring et l'API Telemetry.
  • Affichez les séries temporelles à l'aide de l'explorateur de métriques.

Migrer les tableaux de bord et les règles d'alerte

Mettez à jour vos graphiques et tableaux de bord comme suit :

  1. Si vous surveillez l'utilisation de l'API Cloud Logging ou de l'API Cloud Monitoring à l'aide de graphiques ou de règles d'alerte, créez des graphiques ou des règles d'alerte supplémentaires pour surveiller l'utilisation de l'API Telemetry.

  2. Si les récepteurs de métriques incluent un récepteur otlp ou si votre collecteur récupère des métriques Prometheus avec des caractères UTF-8, mettez à jour vos graphiques et tableaux de bord. L'exportateur otlphttp génère des métriques différentes de l'exportateur googlemanagedprometheus. Pour en savoir plus, consultez la section Différences dans le format des métriques exportées.

    Vous n'avez pas besoin de mettre à jour vos graphiques et tableaux de bord si votre collecteur ne reçoit que des données de métriques Prometheus.

  3. Si vos pipelines de métriques incluent un prometheus récepteur, alors des conflits de flux de données se produiront entre les métriques générées par les otlphttp et googlemanagedprometheus exportateurs. Pour résoudre ces conflits, supprimez l'exportateur googlemanagedprometheus.

Différences dans le format des métriques exportées

Les mises à jour des graphiques et des règles d'alerte basés sur les métriques sont nécessaires en raison des différences suivantes entre les métriques exportées par les exportateurs OTLP et googlemanagedprometheus :

  • L'API Telemetry autorise les caractères point (.) et barre oblique (/) avec dans les noms de métriques. L'exportateur googlemanagedprometheus convertit toutes les instances de ces caractères en trait de soulignement (_). Par exemple, une métrique OTLP appelée prometheus.googleapis.com/foo.bar/gauge est exportée telle quelle par l'exportateur OTLP, mais est exportée en tant que prometheus.googleapis.com/foo_bar/gauge par l'exportateur googlemanagedprometheus.

    Lorsque les métriques sont ingérées, Cloud Monitoring crée des descripteurs de métriques basés sur les noms. La différence dans la façon dont les caractères point (.) et barre oblique (/) sont gérés par les chemins d'ingestion signifie que les descripteurs de métriques résultants diffèrent entre les métriques ingérées à l'aide de l'exportateur googlemanagedprometheus et celles ingérées à l'aide de l'exportateur otlphttp. Si vous utilisez les deux chemins d'ingestion, vous disposez de deux ensembles de métriques. Pour obtenir des résultats complets lors de l'interrogation, vous devez unir manuellement les résultats des versions Prometheus et OTLP des métriques.

  • L'API Telemetry n'ajoute pas d'unité à un nom de métrique lorsqu'une unité est présente, et n'ajoute pas de suffixe _total aux compteurs. Ainsi, une métrique exportée en tant que prometheus.googleapis.com/foo/counter lors de l'utilisation de l'API Telemetry est exportée en tant que prometheus.googleapis.com/foo_seconds_total/counter par l'exportateur googlemanagedprometheus. Cette différence s'applique également aux suffixes _total et _ratio.

Pour en savoir plus sur les différences entre les métriques, consultez la section Différences entre l'exportateur googlemanagedprometheus et l'API Telemetry.

Les règles de transformation ne s'appliquent pas aux métriques avec des caractères UTF-8. Par conséquent, vous devez réécrire vos tableaux de bord et vos règles d'alerte pour utiliser les nouveaux noms de métriques ou utiliser des requêtes qui combinent les anciens et les nouveaux noms de métriques. Nous vous déconseillons d'écrire des règles de processeur pour recréer ces transformations afin de continuer à écrire des métriques UTF-8 comme si elles étaient collectées par l'exportateur googlemanagedprometheus. Cela préserve la rétrocompatibilité, mais sacrifie la compatibilité ascendante, et vous ne pourrez pas utiliser les assets Open Source qui font référence aux noms de métriques UTF-8.

Supprimer les exportateurs spécifiques à un fournisseur

Une fois que vous avez validé les nouveaux flux de données et mis à jour vos tableaux de bord et vos règles d'alerte, supprimez les exportateurs googlecloud/logging et googlemanagedprometheus de la configuration de votre collecteur. Vous devrez peut-être également supprimer les processeurs qui n'étaient utilisés que par les exportateurs qui ont été supprimés de la configuration.

Vous devez mettre à jour à la fois la liste des exportateurs et les pipelines de service.

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

Dépannage

Cette section explique comment résoudre les échecs qui peuvent se produire lorsque vous migrez la configuration de votre collecteur.

Données de métriques manquantes ou pics dans les données de métriques

Si vos données de métriques sont manquantes ou contiennent des pics, vérifiez que vous avez ajouté le processeur metricstarttime à la configuration du collecteur. Pour en savoir plus, consultez la section Ajouter le processeur metricstarttime.

Vous pouvez également consulter les journaux de votre collecteur, les journaux système et les journaux d'audit d'accès aux données pour Monitoring. Par exemple, si une écriture dans une série temporelle échoue, un journal d'audit d'accès aux données incluant la raison de l'échec est généré.

Messages d'erreur concernant l'écriture de séries temporelles

Le système génère des messages d'erreur lorsqu'une tentative d'écriture de données dans une série temporelle échoue. Vous pouvez utiliser ces messages pour comprendre pourquoi l'écriture a échoué et comment résoudre le problème.

  • Message d'erreur indiquant une incompatibilité de valeur :

    "One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."

    Cette erreur se produit si vous avez précédemment envoyé des métriques INT64 target_info, car l'API Telemetry définit le type de valeur de toutes les métriques sur DOUBLE. La meilleure solution à long terme consiste à supprimer le descripteur de la métrique pour les métriques INT64 target_info. Pour supprimer ce descripteur de votre champ d'application des métriques, utilisez ce script Golang.

  • Message d'erreur indiquant que plusieurs sources écrivent des données de séries temporelles :

    "One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."

    Pour résoudre ce problème, supprimez l'exportateur googlemanagedprometheus de la configuration de votre collecteur. Pour en savoir plus, consultez la section Supprimer les exportateurs spécifiques à un fournisseur.

Étape suivante