Zum OTLP-Exporter migrieren

Diese Funktion unterliegt den Bedingungen für Pre‑GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

In diesem Dokument wird beschrieben, wie Sie eine OpenTelemetry Collector-Konfiguration ändern, die einen vorhandenen Exporter verwendet – in diesem Fall den googlemanagedprometheus-Exporter –, um den otlphttp-Exporter und die Telemetry (OTLP) API zu verwenden, telemetry.googleapis.com.

OTLP für Prometheus-Messwerte funktioniert nur, wenn Sie den OpenTelemetry Collector in Version 0.140.0 oder höher verwenden.

Telemetry API aktivieren

Der otlphttp-Exporter schreibt in die Telemetry API. Diese API muss daher in Ihrem Projekt aktiviert sein. Aktivieren Sie die Telemetry API, indem Sie den folgenden Befehl ausführen:

gcloud services enable telemetry.googleapis.com

Kubernetes-Dienstkonto autorisieren

Das Kubernetes-Dienstkonto muss die Berechtigung zur Verwendung der Telemetry API haben. Mit den folgenden Befehlen wird dem Kubernetes-Dienstkonto die erforderliche IAM-Rolle (Identity and Access Management) zugewiesen. Bei diesen Befehlen wird davon ausgegangen, dass Sie die Identitätsföderation von Arbeitslasten für GKE verwenden:

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

Ersetzen Sie die Variable PROJECT_ID durch die ID Ihres Projekts von Google Cloud .

Wenn Ihr Dienstkonto ein anderes Format hat, können Sie den Befehl in der Dokumentation zu Google Cloud Managed Service for Prometheus verwenden, um das Dienstkonto zu autorisieren. Nehmen Sie dazu die folgenden Änderungen vor:

• Ersetzen Sie den Dienstkontonamen gmp-test-sa durch Ihr Dienstkonto.
• Führen Sie den Befehl aus, um die Rolle roles/telemetry.metricsWriter zuzuweisen.

Legen Sie die Umgebungsvariable PROJECT_ID fest.

Legen Sie die Umgebungsvariable PROJECT_ID in Ihrer Collector-Bereitstellung fest. Das Ergebnis sieht so aus:

env:
- name: PROJECT_ID
  value: PROJECT_ID

Suchen Sie den zu ersetzenden Exporter.

Suchen Sie in der Konfigurationsdatei nach dem Exporter und dem Dienst, der den Exporter verwendet:

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

Konfiguration für den otlphttp-Exporter hinzufügen

In diesem Schritt fügen Sie der Konfiguration den otlphttp-Exporter und den metricstarttime-Prozessor hinzu. Dieser zusätzliche Exporter führt dazu, dass der Collector die Messwerte doppelt schreibt.

• Wenn Sie OTLP-native Messwerte verwenden, verursacht das doppelte Schreiben kein Problem, da sich die Struktur der mit den beiden Methoden erstellten Messwertdeskriptoren unterscheidet. Es handelt sich um separate Messwerte.
• Wenn Sie Prometheus-Messwerte verwenden, treten Kollisionen auf, bis Sie den googlemanagedpromethus-Exporter entfernen.

Die aktualisierte Konfiguration sieht so aus:

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]

Nachdem Sie Ihre Messwerte doppelt geschrieben haben, aktualisieren Sie Ihre Dashboards und Benachrichtigungsrichtlinien, damit die neuen Messwertnamen verwendet werden, die vom otlphttp-Exporter generiert wurden. Der otlphttp-Exporter benennt Messwerte nicht in „Prometheus-Stil“ um, indem er Unterstriche verwendet.

Hinweis :Da in der Telemetry API der Werttyp aller Messwerte auf DOUBLE festgelegt ist, kann es zu Konflikten mit Werttypen kommen, insbesondere wenn Sie zuvor INT64-target_info-Messwerte gesendet haben. Wenn es zu Konflikten kommt, ist die beste langfristige Lösung, den Messwertdeskriptor für die INT64-Messwerte target_info zu löschen. Wenn Sie diesen Deskriptor aus Ihrem Messwertbereich löschen möchten, verwenden Sie dieses Golang-Skript.

Konfiguration für den vorherigen Exporteur entfernen

Nachdem Sie Ihre Dashboards und Benachrichtigungen so aktualisiert haben, dass sie auf die aus otlphttp exportierten Messwerte verweisen, entfernen Sie den alten Exporter, in diesem Fall googlemanagedprometheus, aus der Konfiguration. Die überarbeitete Konfiguration sieht so aus:

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]

Dashboards und Benachrichtigungsrichtlinien migrieren, falls erforderlich

Wenn Sie den googlemanagedprometheus-Exporter nur für Prometheus-Messwertdaten verwendet haben, funktionieren Ihre vorhandenen Dashboards und Benachrichtigungsrichtlinien weiterhin, wenn Sie zum OTLP-Exporter wechseln.

Wenn Sie jedoch den googlemanagedprometheus-Exporter verwendet haben, um Daten zu erfassen und zu senden, die ursprünglich mit OTLP ausgegeben wurden, oder wenn Sie Prometheus-Messwerte mit UTF-8-Zeichen erfasst haben, müssen Sie Ihre Dashboards und Benachrichtigungen aktualisieren, damit der UTF-8-Messwertname verwendet wird.

Das liegt an den folgenden Unterschieden zwischen Messwerten, die mit OTLP exportiert werden, und Messwerten, die mit dem googlemanagedprometheus-Exporter exportiert werden:

• Die Telemetry API erlaubt die Zeichen Punkt (.) und Schrägstrich (/) in Messwertnamen. Beim googlemanagedprometheus-Export werden alle Instanzen dieser Zeichen in Unterstriche (_) umgewandelt. Ein OTLP-Messwert namens prometheus.googleapis.com/foo.bar/gauge wird beispielsweise vom OTLP-Exporter unverändert exportiert, vom googlemanagedprometheus-Exporter jedoch als prometheus.googleapis.com/foo_bar/gauge.

  Wenn die Messwerte aufgenommen werden, erstellt Cloud Monitoring Messwertdeskriptoren auf Grundlage der Namen. Aufgrund der unterschiedlichen Verarbeitung von Punkt (.) und Schrägstrich (/) durch die Aufnahmepfade unterscheiden sich die resultierenden Messwertdeskriptoren zwischen Messwerten, die mit dem googlemanagedprometheus-Exporter aufgenommen werden, und Messwerten, die mit dem otlphttp-Exporter aufgenommen werden. Wenn Sie beide Erfassungspfade verwenden, haben Sie zwei Messwertgruppen. Wenn Sie Abfragen ausführen, müssen Sie die Ergebnisse der Prometheus- und OTLP-Versionen der Messwerte manuell zusammenführen, um vollständige Ergebnisse zu erhalten.

• Die Telemetry API hängt keine Einheit an einen Messwertnamen an, wenn eine Einheit vorhanden ist, und kein _total-Suffix an Zähler. Ein Messwert, der mit der Telemetry API als prometheus.googleapis.com/foo/counter exportiert wird, wird vom googlemanagedprometheus-Exporter als prometheus.googleapis.com/foo_seconds_total/counter exportiert. Dieser Unterschied gilt auch für die Suffixe _total und _ratio.

Weitere Informationen zu den Unterschieden zwischen den Messwerten finden Sie unter Unterschiede zwischen dem googlemanagedprometheus-Exporter und der Telemetry API.

Da die Transformationsregeln nicht auf Messwerte mit UTF-8-Zeichen angewendet werden, müssen Sie Ihre Dashboards und Benachrichtigungsrichtlinien entweder so umschreiben, dass die neuen Messwertnamen verwendet werden, oder die alten und neuen Messwertnamen zusammenführen.

Wir empfehlen nicht, Prozessorregeln zu schreiben, um diese Transformationen nachzubilden und weiterhin UTF-8-Messwerte zu schreiben, als wären sie vom googlemanagedprometheus-Exporter erfasst worden. Dadurch wird die Abwärtskompatibilität beibehalten, aber die Vorwärtskompatibilität geht verloren. Außerdem können Sie Open-Source-Assets, die auf die UTF‑8-Messwertnamen verweisen, nicht ohne Weiteres verwenden.