OpenTelemetry Collector unter Container-Optimized OS bereitstellen

In diesem Dokument wird beschrieben, wie Sie den von Google entwickelten OpenTelemetry Collector unter Container-Optimized OS ausführen, um OTLP-Logs, -Messwerte und -Traces aus instrumentierten Anwendungen zu erfassen und diese Daten dann in Google Cloudzu exportieren.

Hinweise

Für die Ausführung des OpenTelemetry-Collectors sind die folgenden Ressourcen erforderlich:

  • Ein Google Cloud-Projekt mit aktivierter Cloud Monitoring API, Cloud Trace API und Cloud Logging API.

    • Wenn Sie kein Google Cloud-Projekt haben, gehen Sie so vor:

      1. Wechseln Sie in der Google Cloud Console zu Neues Projekt:

        Neues Projekt erstellen

      2. Geben Sie im Feld Projektname einen Namen für Ihr Projekt ein und klicken Sie dann auf Erstellen.

      3. Wechseln Sie zu Billing (Abrechnung):

        Zur Abrechnung

      4. Wählen Sie das Projekt aus, das Sie gerade erstellt haben, falls es nicht bereits oben auf der Seite ausgewählt wurde.

      5. Sie werden aufgefordert, ein vorhandenes Zahlungsprofil auszuwählen oder ein neues Zahlungsprofil zu erstellen.

      Die Monitoring API, die Trace API und die Logging API sind für neue Projekte standardmäßig aktiviert.

    • Wenn Sie bereits ein Google Cloud-Projekt haben, dann stellen Sie sicher, dass die Monitoring API, die Trace API und die Logging API aktiviert sind:

      Enable the APIs

  • Eine virtuelle Maschine (VM) mit Container-Optimized OS. Wenn Sie keine VM mit Container-Optimized OS haben, folgen Sie der Anleitung unter Instanzen erstellen und konfigurieren.

  • Eine Installation von gcloud. Informationen zur Installation von gcloud finden Sie unter Google Cloud CLI installieren.

Berechtigungen für den Collector konfigurieren

Container-optimierte Betriebssystem-VMs verwenden standardmäßig das Compute Engine-Standarddienstkonto, PROJECT_NUMBER-compute@developer.gserviceaccount.com. Dieses Dienstkonto hat in der Regel die IAM-Rollen (Identity and Access Management), die zum Schreiben der in diesem Dokument beschriebenen Messwerte und Logs erforderlich sind:

Wenn Sie ein benutzerdefiniertes Dienstkonto für Ihre Instanz konfigurieren, lesen Sie den Hilfeartikel Zugriff auf Dienstkonten verwalten.

Collector bereitstellen

Wenn Sie den von Google erstellten OpenTelemetry Collector ausführen möchten, müssen Sie eine Konfigurationsdatei für Ihre Container-Optimized OS-VM angeben. Sie können das cloud-init-Tool verwenden, um eine Konfigurationsdatei zu erstellen. Im Folgenden finden Sie eine empfohlene cloud-init-Datei für die Verwendung des von Google entwickelten Collectors:

write_files:
- path: /etc/config/config.yaml
  permissions: 0644
  owner: root
  content: |
    receivers:
      # Open two OTLP servers:
      # - On port 4317, open an OTLP GRPC server
      # - On port 4318, open an OTLP HTTP server
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
      otlp:
        protocols:
          grpc:
            endpoint: localhost:4317
          http:
            cors:
              # This effectively allows any origin
              # to make requests to the HTTP server.
              allowed_origins:
              - http://*
              - https://*
            endpoint: localhost:4318

      # Using the prometheus scraper, scrape the Collector's self metrics.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver
      # https://opentelemetry.io/docs/collector/internal-telemetry/
      prometheus/self-metrics:
        config:
          scrape_configs:
          - job_name: otel-self-metrics
            scrape_interval: 1m
            static_configs:
            - targets:
              - localhost:8888

    processors:
      # The batch processor is in place to regulate both the number of requests
      # being made and the size of those requests.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
      batch:
        send_batch_max_size: 200
        send_batch_size: 200
        timeout: 5s

      # The memorylimiter will check the memory usage of the collector process.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
      memory_limiter:
        check_interval: 1s
        limit_percentage: 65
        spike_limit_percentage: 20

      # The resourcedetection processor is configured to detect GCP resources.
      # Resource attributes that represent the GCP resource the collector is
      # running on will be attached to all telemetry that goes through this
      # processor.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
      resourcedetection:
        detectors: [gcp]
        timeout: 10s

      transform/collision:
        metric_statements:
        - context: datapoint
          statements:
          - set(attributes["exported_location"], attributes["location"])
          - delete_key(attributes, "location")
          - set(attributes["exported_cluster"], attributes["cluster"])
          - delete_key(attributes, "cluster")
          - set(attributes["exported_namespace"], attributes["namespace"])
          - delete_key(attributes, "namespace")
          - set(attributes["exported_job"], attributes["job"])
          - delete_key(attributes, "job")
          - set(attributes["exported_instance"], attributes["instance"])
          - delete_key(attributes, "instance")
          - set(attributes["exported_project_id"], attributes["project_id"])
          - delete_key(attributes, "project_id")

    exporters:
      # The googlecloud exporter will export telemetry to different
      # Google Cloud services:
      # Logs -> Cloud Logging
      # Metrics -> Cloud Monitoring
      # Traces -> Cloud Trace
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
      googlecloud:
        log:
          default_log_name: opentelemetry-collector

      # The googlemanagedprometheus exporter will send metrics to
      # Google Managed Service for Prometheus.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
      googlemanagedprometheus:

    service:
      pipelines:
        logs:
          receivers:
          - otlp
          processors:
          - resourcedetection
          - memory_limiter
          - batch
          exporters:
          - googlecloud
        metrics/otlp:
          receivers:
          - otlp
          processors:
          - resourcedetection
          - transform/collision
          - memory_limiter
          - batch
          exporters:
          - googlemanagedprometheus
        metrics/self-metrics:
          receivers:
          - prometheus/self-metrics
          processors:
          - resourcedetection
          - transform/collision
          - memory_limiter
          - batch
          exporters:
          - googlemanagedprometheus
        traces:
          receivers:
          - otlp
          processors:
          - resourcedetection
          - memory_limiter
          - batch
          exporters:
          - googlecloud
      telemetry:
        metrics:
          address: localhost:8888

Wir empfehlen, ein Docker-bridge-Netzwerk zu erstellen, um die Kommunikation zwischen dem Collector-Container und allen anderen Containern auf dem System zu ermöglichen, die Telemetry senden. Führen Sie den folgenden Befehl aus, um das Netzwerk zu erstellen:

docker network create -d bridge otel otel

Führen Sie den Collector-Container mit dem folgenden Befehl aus:

docker run -d \
    --network otel \
    --name opentelemetry-collector \
    -v /etc/config:/etc/config \
    us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.122.1 \
    --config=/etc/config/config.yaml

Der vorherige Befehl führt Folgendes aus:

  • Führt den Collector-Container im Hintergrund aus.
  • Der Collector-Container wird mit dem zuvor erstellten otel-Bridge-Netzwerk verbunden. Andere Container können mit der Bridge verbunden werden, um Telemetriedaten zu senden.
  • Hiermit wird Ihre Konfigurationsdatei im Container bereitgestellt, damit darauf zugegriffen werden kann, um den Collector zu konfigurieren.

Collector konfigurieren

Wir stellen eine OpenTelemetry Collector-Konfiguration für den von Google entwickelten Collector zur Verfügung. Diese Konfiguration ist für die Übermittlung großer Mengen von OTLP-Messwerten, ‑Protokollen und ‑Traces ausgelegt. Diese Konfiguration soll auch häufige Probleme bei der Datenaufnahme verhindern. Sie können der Konfiguration Elemente hinzufügen, wir empfehlen jedoch dringend, keine Elemente zu entfernen.

In diesem Abschnitt werden die bereitgestellte Konfiguration und die wichtigsten Komponenten wie Exporteure, Prozessoren, Empfänger und andere verfügbare Komponenten beschrieben.

Angegebene Collector-Konfiguration

Sie finden die Konfigurationsdatei des Collectors im Verzeichnis google-built-opentelemetry-collector des opentelemetry-operations-collector-Repositorys:

receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

  # Using the prometheus scraper, scrape the Collector's self metrics.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  prometheus/self-metrics:
    config:
      scrape_configs:
      - job_name: otel-self-metrics
        scrape_interval: 1m
        static_configs:
        - targets:
          - localhost:8888

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  # The transform/collision processor ensures that any attributes that may
  # collide with the googlemanagedprometheus exporter's monitored resource
  # construction are moved to a similar name that is not reserved.
  transform/collision:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - transform/collision
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    metrics/self-metrics:
      receivers:
      - prometheus/self-metrics
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  telemetry:
    metrics:
      address: localhost:8888

Exporteure

Die Collector-Konfiguration umfasst die folgenden Exporteure:

  • googlecloud-Export für Protokolle und Traces Dieser Exporter ist mit einem Standardprotokollnamen konfiguriert.

  • googlemanagedprometheus-Exporter für Messwerte. Dieser Exporteur erfordert keine Konfiguration, es gibt jedoch Konfigurationsoptionen. Informationen zu den Konfigurationsoptionen für den googlemanagedprometheus-Exporter finden Sie unter Erste Schritte mit dem OpenTelemetry Collector in der Dokumentation zu Google Cloud Managed Service for Prometheus.

Prozessoren

Die Konfiguration des Collectors umfasst die folgenden Prozessoren:

  • batch: Konfiguriert, um Telemetrieanfragen mit der Google Cloud maximalen Anzahl von Einträgen pro Anfrage oder mit dem Google Cloud Mindestintervall von 5 Sekunden (je nachdem, was zuerst erreicht ist) in Batches zu verarbeiten.

  • memory_limiter: Mit dieser Option wird die Arbeitsspeichernutzung des Collectors begrenzt, um Abstürze aufgrund von Speichermangel zu verhindern. Dazu werden Datenpunkte verworfen, wenn das Limit überschritten wird.

  • resourcedetection: Erkennt automatisch Google Cloud Ressourcenlabels wie project_id.

Empfänger

Die Konfiguration des Collectors enthält nur den otlp-Empfänger. Informationen zum Instrumentieren Ihrer Anwendungen, um OTLP-Traces und ‑Messwerte an den OTLP-Endpunkt des Collectors zu senden, finden Sie unter Instrumentierungsansatz auswählen.

Verfügbare Komponenten

Der von Google entwickelte OpenTelemetry Collector enthält die Komponenten, die die meisten Nutzer benötigen, um die Funktionen von Google Cloud Observability optimal nutzen zu können. Eine vollständige Liste der verfügbaren Komponenten finden Sie im opentelemetry-operations-collector-Repository unter Components.

Wenn Sie Änderungen oder Ergänzungen an den verfügbaren Komponenten anfordern möchten, erstellen Sie im opentelemetry-operations-collector-Repository eine Funktionsanfrage.

Telemetrie generieren

Sie können Ihre Konfiguration mit dem Open-Source-Tool telemetrygen testen. Das OpenTelemetry-Projekt stellt einen Container in der GitHub Container Registry bereit.

Ersetzen Sie vor dem Ausführen der folgenden Befehle die folgenden Platzhalter, wenn Sie die Standardwerte in den Docker-Befehlen unter Einen Collector bereitstellen geändert haben:

  • otel: Der Name, den Sie beim Erstellen des Docker-bridge-Netzwerks angegeben haben.
  • opentelemetry-collector: Der Name, den Sie beim Ausführen des Containers angegeben haben.

Protokolle erstellen

Führen Sie den folgenden Befehl aus, um Protokolle mit dem telemetrygen-Tool zu generieren:

docker run \
  --net=otel \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.105.0 \
  logs --otlp-insecure --rate=3 --duration=5m \
  --otlp-endpoint=opentelemetry-collector:4317

Messwerte generieren

Führen Sie den folgenden Befehl aus, um mit dem telemetrygen-Tool Messwerte zu generieren:

docker run \
  --net=otel \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.105.0 \
  metrics --otlp-insecure --rate=0.1 --duration=5m \
  --otlp-endpoint=opentelemetry-collector:4317

Messwerte generieren

Führen Sie den folgenden Befehl aus, um mit dem telemetrygen-Tool Protokolle zu generieren:

docker run \
  --net=otel \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.105.0 \
  traces --otlp-insecure --rate=3 --duration=5m \
  --otlp-endpoint=opentelemetry-collector:4317

Nach einigen Minuten beginnt die von der Anwendung generierte Telemetrie, für jedes Signal durch den Collector an die Google Cloud Console zu fließen.

Telemetriedaten ansehen

Der von Google entwickelte OpenTelemetry Collector sendet Messwerte, Protokolle und Traces aus Ihren instrumentierten Anwendungen an Google Cloud Observability. Der Collector sendet auch Messwerte zur Selbstbeobachtung. In den folgenden Abschnitten wird beschrieben, wie Sie diese Telemetriedaten aufrufen.

Messwerte ansehen

Der von Google entwickelte OpenTelemetry Collector erfasst Prometheus-Messwerte, die Sie mit dem Metrics Explorer aufrufen können. Die erfassten Messwerte hängen von der Instrumentierung der App ab. Der von Google entwickelte Collector schreibt jedoch auch einige eigene Messwerte.

So rufen Sie die vom OpenTelemetry-Collector von Google erfassten Messwerte auf:

  1. Rufen Sie in der Google Cloud Console die Seite Metrics Explorer auf.

    Zum Metrics Explorer

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.

  2. Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Google Cloud-Projekt aus. Wählen Sie für App Hub-Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt des für Anwendungen aktivierten Ordners aus.
  3. Maximieren Sie im Element Messwert das Menü Messwert auswählen, geben Sie Prometheus Target in die Filterleiste ein und wählen Sie dann über die Untermenüs einen bestimmten Ressourcentyp und Messwert aus:
    1. Wählen Sie im Menü Aktive Ressourcen die Option Prometheus-Ziel aus.
    2. Einen Messwert wählen Sie in den Menüs Aktive Messwertkategorien und Aktive Messwerte aus. Messwerte, die vom OpenTelemetry Collector von Google erfasst werden, haben das Präfix prometheus.googleapis.com.
    3. Klicken Sie auf Übernehmen.
  4. Konfigurieren Sie, wie die Daten angezeigt werden.

    Wenn die Messungen für einen Messwert kumulativ sind, normalisiert Metrics Explorer die gemessenen Daten automatisch nach dem Ausrichtungszeitraum. Dadurch wird im Diagramm eine Rate angezeigt. Weitere Informationen finden Sie unter Arten, Typen und Umwandlungen.

    Wenn ganzzahlige oder doppelte Werte gemessen werden, z. B. mit den counter-Messwerten, summiert der Metrics Explorer automatisch alle Zeitreihen. Wenn Sie dieses Verhalten ändern möchten, legen Sie im ersten Menü des Eintrags Aggregation die Option Keine fest.

    Weitere Informationen zum Konfigurieren eines Diagramms finden Sie unter Messwerte bei Verwendung von Metrics Explorer auswählen.

Traces ansehen

So rufen Sie Ihre Trace-Daten auf:

  1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

    Zum Trace Explorer

    Sie können diese Seite auch über die Suchleiste finden.

  2. Wählen Sie in der Symbolleiste der Google Cloud Console Ihr Google Cloud-Projekt aus. Wählen Sie für App Hub-Konfigurationen das App Hub-Hostprojekt oder das Verwaltungsprojekt des Ordners für Anwendungen aus.
  3. Wählen Sie auf der Seite im Tabellenbereich eine Zeile aus.

  4. Wählen Sie im Gantt-Diagramm im Bereich Trace-Details einen Span aus.

    Ein Steuerfeld mit Informationen zur getrackten Anfrage wird geöffnet. Zu diesen Details gehören die Methode, der Statuscode, die Anzahl der Byte und der User-Agent des Aufrufers.

  5. Wählen Sie den Tab Logs und Ereignisse aus, um die mit diesem Trace verknüpften Logs aufzurufen.

    Auf dem Tab werden einzelne Logs angezeigt. Maximieren Sie den Logeintrag, um die Details anzusehen. Sie können auch auf Logs ansehen klicken und das Log mit dem Log-Explorer aufrufen.

Weitere Informationen zur Verwendung von Cloud Trace-Explorer finden Sie unter Traces suchen und untersuchen.

Logs ansehen

Im Log-Explorer können Sie Ihre Logs prüfen und sich auch die zugehörigen Traces ansehen, sofern vorhanden.

  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

    Zum Log-Explorer

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

  2. Suchen Sie einen Logeintrag aus Ihrer instrumentierten App. Maximieren Sie den Logeintrag, um die Details aufzurufen.

  3. Klicken Sie bei einem Logeintrag mit einer Trace-Nachricht auf Traces und wählen Sie dann Trace-Details anzeigen aus.

    Der Bereich Trace-Details wird geöffnet und zeigt den ausgewählten Trace an.

Weitere Informationen zur Verwendung des Log-Explorers finden Sie unter Logs mit dem Log-Explorer ansehen.

Collector beobachten und debuggen

Der von Google entwickelte OpenTelemetry Collector bietet automatisch Messwerte zur Selbstbeobachtbarkeit, mit denen Sie die Leistung überwachen und eine kontinuierliche Verfügbarkeit der OTLP-Aufnahmepipeline gewährleisten können.

Wenn Sie den Collector überwachen möchten, installieren Sie das Beispiel-Dashboard für den Collector. Dieses Dashboard bietet einen übersichtlichen Überblick über verschiedene Messwerte des Collectors, einschließlich Betriebszeit, Arbeitsspeichernutzung und API-Aufrufe an Google Cloud Observability.

So installieren Sie das Dashboard:

  1. Rufen Sie in der Google Cloud Console die Seite Dashboards auf.

    Dashboards aufrufen

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.

  2. Klicken Sie auf Dashboard-Vorlagen.
  3. Suchen Sie nach dem Dashboard OpenTelemetry Collector.
  4. Optional: Wenn Sie eine Vorschau des Dashboards aufrufen möchten, wählen Sie es aus.

  5. Klicken Sie auf Dashboard in Liste aufnehmen und füllen Sie das Dialogfeld aus.

    Im Dialogfeld können Sie den Namen des Dashboards auswählen und dem Dashboard Labels hinzufügen.

Weitere Informationen zum Installieren von Dashboards finden Sie unter Dashboard-Vorlage installieren.