Collectors für die Verwendung von OTLP-Exportern migrieren

Die Telemetry (OTLP) API ist eine Implementierung des OpenTelemetry-Protokolls. Durch die Unterstützung von OTLP können Sie Ihrer Collector-Konfiguration generische otlphttp- und otlp_grpc/otlp_logs-Exporter hinzufügen und so anbieterspezifische Exporter vermeiden. Anwendungen können Log-, Messwert- und Trace-Daten an die Telemetry API senden.

Diese Anleitung gilt für Sie, wenn in der Konfiguration Ihres Collectors der googlecloud Exporter oder der googlemanagedprometheus Exporter verwendet wird:

So migrieren Sie zu OTLP-Exportern:

  1. Telemetry API aktivieren
  2. Collector-Dienstkonto autorisieren
  3. Umgebungsvariable GOOGLE_CLOUD_PROJECT festlegen
  4. Erweiterung googleclientauth hinzufügen
  5. Exporter otlphttp und otlp_grpc/otlp_logs hinzufügen
  6. Prozessoren hinzufügen
  7. Dienstpipelines aktualisieren
  8. Konfiguration validieren
  9. Dashboards und Benachrichtigungsrichtlinien migrieren
  10. Anbieterspezifische Exporter entfernen

Telemetry API aktivieren

Die OTLP-Exporter schreiben in die Telemetry API. Diese API muss daher in Ihrem Projekt aktiviert sein. Führen Sie den folgenden Befehl aus, um die Telemetry API zu aktivieren:

gcloud services enable telemetry.googleapis.com

Collector-Dienstkonto autorisieren

Der Collector authentifiziert sich bei Google Cloud APIs mit der Identität der Umgebung, in der er ausgeführt wird. Das Dienstkonto, unter dem Ihr Collector ausgeführt wird, muss die Berechtigung haben, die Telemetry API zu verwenden, um Log-, Messwert- und Trace-Daten zu schreiben. Da die Telemetry API eine Consumer-API ist, müssen Sie explizit das Google Cloud Projekt angeben, dessen Kontingent von API-Aufrufen verbraucht wird, und dem Dienstkonto die Berechtigungen gewähren, die zum Verbrauchen des Kontingents dieses Projekts erforderlich sind.

Erforderliche Rollen

Damit das Dienstkonto, unter dem Ihr Collector ausgeführt wird, die erforderlichen Berechtigungen zum Senden von Log-, Messwert- und Trace-Daten hat, bitten Sie Ihren Administrator, dem Dienstkonto, unter dem Ihr Collector ausgeführt wird, die folgenden IAM-Rollen für Ihr Projekt zu gewähren:

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Senden von Log-, Messwert- und Trace-Daten erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Log-, Messwert- und Trace-Daten zu senden:

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

Kubernetes-Dienstkonto

Wenn Sie den Collector in Google Kubernetes Engine (GKE) mit Workload Identity Federation for GKE bereitstellen, gewähren Sie die erforderlichen Rollen Ihrem Kubernetes-Dienstkonto.

Mit den folgenden Befehlen können Sie die erforderlichen Rollen gewähren, wenn Ihr API-Kontingent aus demselben Google Cloud Projekt stammt, das das Ziel der Telemetry API-Aufrufe ist. Ersetzen Sie vor dem Ausführen der Befehle PROJECT_ID durch die ID Ihres Projekts. Wenn Sie jedoch ein separates Kontingentprojekt verwenden, ersetzen Sie PROJECT_ID im zweiten Befehl durch die ID Ihres Kontingentprojekts:

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

Dienstkonto für die Workload Identity Federation for GKE

Wenn Sie ein Dienstkonto für die Workload Identity Federation for GKE konfiguriert haben, 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 gmp-test-sa durch den Namen Ihres Dienstkontos.
  • Führen Sie den Befehl aus, um die erforderlichen Rollen zum Schreiben von Log-, Messwert- und Trace-Daten zu gewähren.

Anderes Dienstkonto

Wenn Sie den Collector auf einer Compute Engine-VM oder außerhalb von GKE ausführen, gewähren Sie die erforderlichen Rollen dem Google Cloud Dienstkonto, das von Ihrer Bereitstellung verwendet wird.

Umgebungsvariable GOOGLE_CLOUD_PROJECT festlegen

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

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

Erweiterung googleclientauth hinzufügen

Fügen Sie Ihrer Collector-Konfiguration die Erweiterung googleclientauth hinzu. Die Telemetry API ist eine Consumer-API und erfordert, dass Sie sowohl Ihr Google Cloud Projekt als auch Ihr Kontingentprojekt angeben. Das Ergebnis sieht in etwa so aus:

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

Exporter otlphttp und otlp_grpc/otlp_logs hinzufügen

Verwenden Sie den otlphttp-Exporter, um Messwert- und Trace-Daten im OTLP-Format an Ihr Projekt zu senden, und den otlp_grpc/otlp_logs-Exporter, um Logdaten zu senden. Konfigurieren Sie beide Exporter mit der Erweiterung googleclientauth.

Das Ergebnis sieht in etwa so aus:

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

Für den otlp_grpc/otlp_logs-Exporter muss das Feld endpoint im Format host:port angegeben werden.

Prozessoren hinzufügen

In diesem Abschnitt werden die Prozessoren aufgeführt, die Sie Ihrem Collector hinzufügen müssen. Es gibt noch weitere Prozessoren, die Sie verwenden können. Beispielsweise enthalten Google-Built OpenTelemetry Collector-Konfigurationen in der Regel den memory_limiter-Prozessor und einen, der Messwertdaten transformiert. Ein Beispiel finden Sie unter Google-Built OpenTelemetry Collector in GKE bereitstellen.

Prozessor resource/gcp_project_id hinzufügen

Fügen Sie einen resource Prozessor hinzu, der Informationen zu Ihrem Google Cloud Projekt erfasst.

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

Prozessor resourcedetection hinzufügen

Wenn Sie in Google Cloudausführen, sollten Sie den resourcedetection Prozessor hinzufügen. Dieser Prozessor kann automatisch Informationen zu Ihrer Architektur ermitteln.

Die folgende Konfiguration sucht nach den Standard-Umgebungsvariablen von OpenTelemetry und fragt dann den Google Cloud Metadatenserver ab, um Informationen zu Ihrer Infrastruktur zu erfassen:

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

Prozessor batch hinzufügen

Um Ihre Telemetriedaten effizienter an Ihr Google Cloud Projekt zu senden, empfehlen wir die Verwendung des batch Prozessors.

Der Google-Built OpenTelemetry Collector verwendet beispielsweise die folgende Konfiguration für den Batch-Prozessor:

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

Prozessor metricstarttime hinzufügen

Fügen Sie der Konfiguration den Prozessor metricstarttime hinzu. Dieser Prozessor sorgt dafür, dass kumulative Messwerte sowohl eine Startzeit als auch eine Beobachtungszeit enthalten. Standardmäßig enthalten Prometheus-Messwerte nur die aktuelle Zeit. Wenn Sie diesen Prozessor also weglassen und Ihre Anwendung Prometheus-Messwerte generiert, werden Ihre Messwertdaten möglicherweise abgelehnt oder es treten Datenspitzen auf.

Sie müssen diesen Prozessor hinzufügen, wenn Ihr Collector Prometheus-Messwerte empfängt.

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

Prozessor `transform` hinzufügen

Fügen Sie den folgenden transform-Prozessor hinzu, um die Instrumentierungsquelle und -version in Ihren Logdaten beizubehalten:

  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

Dienstpipelines aktualisieren

Aktualisieren Sie als Nächstes die Pipelines Ihres Collectors, um die Exporter otlp_grpc/otlp_logs und otlphttp zu verwenden. Bei Log- und Trace-Daten werden durch diese Anleitung die aktuellen Exporter durch die entsprechenden OTLP-Exporter ersetzt. Bei Messwertdaten führen diese Anweisungen zu doppelten Schreibvorgängen. Mit diesem Ansatz können Sie prüfen, ob der OTLP-Exporter Messwertdaten an Ihr Google Cloud Projekt sendet. Außerdem können Sie Diagramme und Benachrichtigungsrichtlinien aktualisieren, bevor Sie die Datenstreams vom ursprünglichen Exporter deaktivieren.

Nehmen Sie die folgenden Änderungen an den Pipeline-Konfigurationen Ihres Collectors vor:

  1. Fügen Sie der service-Konfiguration die Erweiterung googleclientauth hinzu.

  2. Ersetzen Sie für Ihre Logpipeline googlecloud/logging durch otlp_grpc/otlp_logs und fügen Sie dann der Liste der Prozessoren der Pipeline die folgenden Prozessoren hinzu:

    • resource/gcp_project_id
    • transform/otlp_grpc/preserve_instrumentation_source_version
    • resourcedetection (wenn Sie diesen Prozessor hinzugefügt haben)
    • batch

    Diese Konfiguration führt einen einzelnen Schreibvorgang für Logdaten aus. Wenn Sie Ihre Logdaten doppelt schreiben möchten, fügen Sie der Liste der Exporter den otlp_grpc/otlp_logs-Exporter hinzu.

  3. Fügen Sie für Ihre Messwertpipeline den otlphttp-Exporter zusammen mit dem googlemanagedprometheus-Exporter der Liste der Exporter der Pipeline hinzu und fügen Sie dann die folgenden Prozessoren hinzu:

    • resource/gcp_project_id
    • metricstarttime
    • resourcedetection (wenn Sie diesen Prozessor hinzugefügt haben)
    • batch

    Diese Konfiguration führt einen doppelten Schreibvorgang für Messwertdaten aus. Nachdem Sie den Messwertdatenstream validiert und Diagramme und Benachrichtigungsrichtlinien aktualisiert haben, entfernen Sie den Prometheus-Exporter.

  4. Ersetzen Sie für Ihre Trace-Pipeline den aktuellen Exporter durch den otlphttp-Exporter und fügen Sie dann die folgenden Prozessoren hinzu:

    • resource/gcp_project_id
    • resourcedetection (wenn Sie diesen Prozessor hinzugefügt haben)
    • batch

    Diese Konfiguration führt einen einzelnen Schreibvorgang für Trace-Daten aus.

Das Ergebnis dieser Änderungen sieht in etwa so aus:

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"]

Im vorherigen Snippet wird der OTLP-Empfänger für Ihre Log-, Messwert- und Trace-Daten verwendet. Ihre Collector-Konfiguration kann abweichen. Wenn Sie beispielsweise eine Anwendung haben, die strukturierte Logdaten schreibt, ist der filelog-Empfänger geeignet.

Konfiguration validieren

Starten Sie Ihre Bereitstellung neu und prüfen Sie dann, ob Ihre otlphttp und otlp_grpc/otlp_logs Exporter Daten an Ihr Google Cloud Projekt senden. So prüfen Sie Ihre Konfiguration:

  • Fragen Sie Ihre Logeinträge nach Fehlern im Zusammenhang mit dem Schreiben von Telemetriedaten ab.
  • Sehen Sie sich die Fehlerraten für die Cloud Logging API, die Cloud Monitoring API und die Telemetry API an.
  • Sehen Sie sich Zeitreihen mit dem Metrics Explorer an.

Dashboards und Benachrichtigungsrichtlinien migrieren

Aktualisieren Sie Ihre Diagramme und Dashboards so:

  1. Wenn Sie die Nutzung der Cloud Logging API oder der Cloud Monitoring API mit Diagrammen oder Benachrichtigungsrichtlinien beobachten, erstellen Sie zusätzliche Diagramme oder Benachrichtigungsrichtlinien, um die Nutzung der Telemetry API zu beobachten.

  2. Wenn die Messwertempfänger einen otlp-Empfänger enthalten oder Ihr Collector Prometheus-Messwerte mit UTF-8-Zeichen erfasst, aktualisieren Sie Ihre Diagramme und Dashboards. Der otlphttp-Exporter generiert andere Messwerte als der googlemanagedprometheus-Exporter. Weitere Informationen finden Sie unter Unterschiede im Format exportierter Messwerte.

    Sie müssen Ihre Diagramme und Dashboards nicht aktualisieren, wenn Ihr Collector nur Prometheus-Messwertdaten empfängt.

  3. Wenn Ihre Messwertpipelines einen prometheus Empfänger enthalten, treten Kollisionen zwischen Datenstreams auf, die von den otlphttp und googlemanagedprometheus Exportern generiert werden. Entfernen Sie den googlemanagedprometheus Exporter, um diese Kollisionen zu beheben.

Unterschiede im Format exportierter Messwerte

Die Aktualisierungen an messwertbasierten Diagrammen und Benachrichtigungsrichtlinien sind aufgrund der folgenden Unterschiede zwischen Messwerten erforderlich, die von den OTLP- und googlemanagedprometheus-Exportern exportiert werden:

  • Die Telemetry API erlaubt die Zeichen Punkt (.) und Schrägstrich (/) mit in Messwertnamen. Der googlemanagedprometheus-Exporter konvertiert alle Instanzen dieser Zeichen in Unterstriche (_). Beispiel: Ein OTLP-Messwert mit dem Namen prometheus.googleapis.com/foo.bar/gauge wird 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 Abfragen vollständige Ergebnisse zu erhalten, müssen Sie die Ergebnisse aus den Prometheus- und OTLP-Versionen der Messwerte manuell zusammenführen.

  • Die Telemetry API hängt keine Einheit an einen Messwertnamen an, wenn eine Einheit vorhanden ist, und sie hängt kein _total-Suffix an Zähler an. 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 Unterschieden zwischen Messwerten finden Sie unter Unterschiede zwischen dem googlemanagedprometheus Exporter und der Telemetry API.

Transformationsregeln gelten nicht für Messwerte mit UTF-8-Zeichen. Daher müssen Sie Ihre Dashboards und Benachrichtigungsrichtlinien entweder so umschreiben, dass die neuen Messwertnamen verwendet werden, oder Abfragen verwenden, die die alten und neuen Messwertnamen kombinieren. 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 googlemanagedprometheusExporter erfasst worden. Dadurch wird die Abwärtskompatibilität beibehalten, aber die Aufwärtskompatibilität geht verloren und Sie können keine Open-Source-Assets verwenden, die auf die UTF-8-Messwertnamen verweisen.

Anbieterspezifische Exporter entfernen

Nachdem Sie die neuen Datenstreams validiert und Ihre Dashboards und Benachrichtigungsrichtlinien aktualisiert haben, entfernen Sie die Exporter googlecloud/logging und googlemanagedprometheus aus Ihrer Collector-Konfiguration. Möglicherweise müssen Sie auch Prozessoren entfernen, die nur von den Exportern verwendet wurden, die aus der Konfiguration entfernt wurden.

Sie müssen sowohl die Liste der Exporter als auch die Dienstpipelines aktualisieren.

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"]

Fehlerbehebung

In diesem Abschnitt wird beschrieben, wie Sie Fehler beheben, die bei der Migration der Konfiguration Ihres Collectors auftreten können.

Fehlende Messwertdaten oder Spitzen bei Messwertdaten

Wenn Ihre Messwertdaten fehlen oder Spitzen enthalten, prüfen Sie, ob Sie der Konfiguration des Collectors den Prozessor metricstarttime hinzugefügt haben. Weitere Informationen finden Sie unter Prozessor metricstarttime hinzufügen.

Sie können auch Ihre Collector-Logs, Systemlogs und die Audit-Logs zum Datenzugriff für Monitoring prüfen. Wenn beispielsweise ein Schreibvorgang in eine Zeitreihe fehlschlägt, wird ein Audit-Log zum Datenzugriff mit der Fehlerursache generiert.

Fehlermeldungen zum Schreiben von Zeitreihen

Das System generiert Fehlermeldungen, wenn ein Versuch, Daten in eine Zeitreihe zu schreiben, fehlschlägt. Anhand dieser Meldungen können Sie nachvollziehen, warum der Schreibvorgang fehlgeschlagen ist und wie Sie das Problem beheben können.

  • Fehlermeldung, die auf eine Wertabweichung hinweist:

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

    Dieser Fehler tritt auf, wenn Sie zuvor INT64-target_info-Messwerte gesendet haben, da die Telemetry API den Werttyp aller Messwerte auf DOUBLE festlegt. Die beste langfristige Lösung besteht darin, den Messwertdeskriptor für die INT64-target_info-Messwerte zu löschen. Verwenden Sie dieses Golang-Skript, um diesen Deskriptor aus Ihrem Messwertbereich zu löschen.

  • Fehlermeldung, die darauf hinweist, dass mehrere Quellen Zeitreihendaten schreiben:

    "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."

    Entfernen Sie den googlemanagedprometheus-Exporter aus der Konfiguration Ihres Collectors, um dieses Problem zu beheben. Weitere Informationen finden Sie unter Anbieterspezifische Exporter entfernen.

Nächste Schritte