Zum OTLP-Exporter migrieren

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 API (OTLP) zu verwenden, telemetry.googleapis.com.

OTLP für Prometheus-Messwerte funktioniert nur mit OpenTelemetry Collector Version 0.140.0 oder höher.

Telemetry API aktivieren

Der otlphttp-Exporter schreibt in die Telemetry API. Daher muss diese API in Ihrem Projekt aktiviert sein. Aktivieren Sie die Telemetry API mit dem folgenden Befehl:

gcloud services enable telemetry.googleapis.com

Kubernetes-Dienstkonto autorisieren

Das Kubernetes-Dienstkonto muss die Berechtigung haben, die Telemetry API zu verwenden. 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 PROJECT_ID Variable durch die ID Ihres Google Cloud Projekts.

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.

Umgebungsvariable PROJECT_ID festlegen

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

env:
- name: PROJECT_ID
  value: PROJECT_ID

Zu ersetzenden Exporter suchen

Suchen Sie in Ihrer Konfigurationsdatei den Exporter und den 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 von den beiden Methoden erstellten Messwertdeskriptoren unterscheidet. Es handelt sich um separate Messwerte.
  • Wenn Sie Prometheus-Messwerte verwenden, treten Konflikte auf, bis Sie den Exporter googlemanagedpromethusentfernen.

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]

Aktualisieren Sie nach dem doppelten Schreiben Ihrer Messwerte, Ihre Dashboards und Benachrichtigungsrichtlinien um die neuen Messwertnamen zu verwenden, die vom otlphttp Exporter generiert wurden. Der otlphttp-Exporter benennt Messwerte nicht in „Prometheus-Stil“ um und ersetzt keine Unterstriche.

Konfiguration für den vorherigen Exporter entfernen

Nachdem Sie Ihre Dashboards und Benachrichtigungen aktualisiert haben, um auf die mit otlphttp exportierten Messwerte zu 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 auch nach dem Wechsel zum OTLP-Exporter.

Wenn Sie den googlemanagedprometheus-Exporter jedoch zum Erfassen und Senden von Daten verwendet haben, die ursprünglich mit OTLP ausgegeben wurden, oder wenn Sie Prometheus-Messwerte mit UTF-8-Zeichen extrahiert haben, müssen Sie Ihre Dashboards und Benachrichtigungen aktualisieren, um den UTF-8-Messwertnamen zu verwenden.

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

  • Die Telemetry API erlaubt die Zeichen Punkt (.) und Schrägstrich (/) mit in Messwertnamen. Der googlemanagedprometheus-Exporter konvertiert alle Instanzen dieser Zeichen in Unterstriche (_). Ein OTLP-Messwert mit dem Namen 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 der Zeichen Punkt (.) und Schrägstrich (/) durch die Aufnahmepfade unterscheiden sich die resultierenden Messwertdeskriptoren zwischen Messwerten, die mit dem googlemanagedprometheus-Exporter aufgenommen wurden, und solchen, die mit dem otlphttp-Exporter aufgenommen wurden. Wenn Sie beide Aufnahmepfade verwenden, haben Sie zwei Messwertgruppen. Um bei der Abfrage vollständige Ergebnisse zu erhalten, müssen Sie die Ergebnisse aus den Prometheus- und OTLP-Versionen der Messwerte manuell zusammenführen.

  • Die Telemetry API fügt einem Messwertnamen keine Einheit hinzu, wenn eine Einheit vorhanden ist, und fügt Zählern kein Suffix _total hinzu. 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 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 neu zu erstellen, damit UTF-8-Messwerte weiterhin so geschrieben werden, als wären sie vom googlemanagedprometheus-Exporter erfasst worden. Dadurch wird die Abwärtskompatibilität beibehalten, aber die Aufwärtskompatibilität geht verloren und Sie können Open-Source-Assets, die auf die UTF-8-Messwertnamen verweisen, nicht einfach verwenden.