Migrer vers l'exportateur OTLP

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document explique comment modifier une configuration OpenTelemetry Collector qui utilise un exportateur existant (dans ce cas, l'exportateur googlemanagedprometheus) pour utiliser l'exportateur otlphttp et l'API Telemetry (OTLP), telemetry.googleapis.com.

OTLP pour les métriques Prometheus ne fonctionne que lorsque vous utilisez le collecteur OpenTelemetry version 0.140.0 ou ultérieure.

Activer l'API Telemetry

L'exportateur otlphttp écrit dans l'API Telemetry. Cette API doit donc être activée dans votre projet. Activez l'API Telemetry en exécutant la commande suivante :

gcloud services enable telemetry.googleapis.com

Autoriser le compte de service Kubernetes

Le compte de service Kubernetes doit être autorisé à utiliser l'API Telemetry. Les commandes suivantes attribuent le rôle IAM (Identity and Access Management) nécessaire au compte de service Kubernetes. Ces commandes supposent que vous utilisez la fédération d'identité de charge de travail pour GKE :

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

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

Remplacez la variable PROJECT_ID par l'ID de votre projet Google Cloud .

Si votre compte de service a un format différent, 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 le nom du compte de service gmp-test-sa par le vôtre.
• Exécutez la commande pour attribuer le rôle roles/telemetry.metricsWriter.

Définir la variable d'environnement PROJECT_ID

Définissez la variable d'environnement PROJECT_ID dans votre déploiement de collecteur. Le résultat se présente comme suit :

env:
- name: PROJECT_ID
  value: PROJECT_ID

Localisez l'exportateur à remplacer.

Dans votre fichier de configuration, localisez l'exportateur et le service qui l'utilise :

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

Ajouter une configuration pour l'exportateur otlphttp

Au cours de cette étape, vous allez ajouter l'exportateur otlphttp et le processeur metricstarttime à la configuration. Cet exportateur supplémentaire entraîne la double écriture des métriques par le collecteur.

• Si vous utilisez des métriques OTLP natives, la double écriture ne pose aucun problème, car la structure des descripteurs de métriques créés par les deux méthodes diffère. Il s'agit de deux métriques distinctes.
• Si vous utilisez des métriques Prometheus, vous verrez des collisions jusqu'à ce que vous supprimiez l'exportateur googlemanagedpromethus.

La configuration mise à jour se présente comme suit :

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

Après avoir écrit vos métriques en double, mettez à jour vos tableaux de bord et vos règles d'alerte pour utiliser les nouveaux noms de métriques générés par l'exportateur otlphttp. L'exportateur otlphttp ne renomme pas les métriques au format Prometheus en remplaçant les espaces par des traits de soulignement.

Remarque : Étant donné que l'API Telemetry définit le type de valeur de toutes les métriques sur DOUBLE, nous nous attendons à ce qu'il puisse y avoir des conflits de type de valeur, en particulier si vous avez déjà envoyé des métriques INT64 target_info. Si vous rencontrez des conflits, 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.

Supprimer la configuration de l'ancien exportateur

Après avoir mis à jour vos tableaux de bord et vos alertes pour qu'ils fassent référence aux métriques exportées otlphttp, supprimez l'ancien exportateur, googlemanagedprometheus dans ce cas, de la configuration. La configuration révisée se présente comme suit :

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

Migrer les tableaux de bord et les règles d'alerte, si nécessaire

Si vous avez utilisé l'exportateur googlemanagedprometheus uniquement pour les données de métriques Prometheus, vos tableaux de bord et règles d'alerte existants continueront de fonctionner lorsque vous passerez à l'exportateur OTLP.

Toutefois, si vous avez utilisé l'exportateur googlemanagedprometheus pour collecter et envoyer des données initialement émises à l'aide d'OTLP, ou si vous avez récupéré des métriques Prometheus avec des caractères UTF-8, vous devez mettre à jour vos tableaux de bord et vos alertes pour utiliser le nom de métrique UTF-8.

Cela est dû aux différences suivantes entre les métriques exportées à l'aide d'OTLP et celles exportées à l'aide de l'exportateur googlemanagedprometheus :

• L'API Telemetry autorise les caractères point (.) et barre oblique (/) 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 sous le nom 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 en fonction des 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 obtenus 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 fusionner 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 elle n'ajoute pas de suffixe _total aux compteurs. Ainsi, une métrique exportée en tant que prometheus.googleapis.com/foo/counter à l'aide 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 Différences entre l'exportateur googlemanagedprometheus et l'API Telemetry.

Étant donné que les règles de transformation ne s'appliquent pas aux métriques comportant des caractères UTF-8, vous devez réécrire vos tableaux de bord et vos règles d'alerte pour utiliser les nouveaux noms de métriques ou pour regrouper 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 permet de conserver la rétrocompatibilité, mais au détriment de la compatibilité ascendante. Vous ne pourrez pas non plus utiliser facilement les ressources Open Source qui font référence aux noms de métriques UTF-8.