Collector bereitstellen und verwenden

In diesem Dokument wird beschrieben, wie Sie den OpenTelemetry Collector bereitstellen, den Collector für die Verwendung des otlphttp Exporters und der Telemetry API (OTLP) konfigurieren und einen Telemetriegenerator ausführen, um Messwerte in Cloud Monitoring zu schreiben. Sie können diese Messwerte dann in Cloud Monitoring aufrufen.

Wenn Sie Google Kubernetes Engine verwenden, können Sie Managed OpenTelemetry for GKEverwenden, anstatt einen OpenTelemetry Collector, der die Telemetry API verwendet, manuell bereitzustellen und zu konfigurieren.

Wenn Sie ein SDK verwenden, um Messwerte direkt aus einer Anwendung an die Telemetry API zu senden, finden Sie weitere Informationen und Beispiele unter SDKs zum Senden von Messwerten aus Anwendungen verwenden für zusätzliche Informationen und Beispiele.

Sie können einen OpenTelemetry Collector und die Telemetry API auch in Verbindung mit der OpenTelemetry-Instrumentierung ohne Code verwenden. Weitere Informationen finden Sie unter OpenTelemetry-Instrumentierung ohne Code für Java verwenden.

Hinweis

In diesem Abschnitt wird beschrieben, wie Sie Ihre Umgebung für die Bereitstellung und Verwendung des Collectors einrichten.

Projekt auswählen oder erstellen Google Cloud

Wählen Sie ein Google Cloud Projekt für diese Anleitung aus. Wenn Sie noch kein Projekt haben, erstellen Sie eines: Google Cloud

  1. Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Konto haben Google Cloud, erstellen Sie ein Konto, um zu testen, wie sich unsere Produkte in realen Szenarien schlagen. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

Befehlszeilentools installieren

In diesem Dokument werden die folgenden Befehlszeilentools verwendet:

  • gcloud
  • kubectl

Die Tools gcloud und kubectl sind Teil der Google Cloud CLI. Informationen zur Installation finden Sie unter Komponenten der Google Cloud CLI verwalten. Führen Sie den folgenden Befehl aus, um die installierten gcloud CLI-Komponenten aufzurufen:

gcloud components list

Führen Sie die folgenden Befehle aus, um die gcloud CLI zu konfigurieren:

gcloud auth login
gcloud config set project PROJECT_ID

APIs aktivieren

Aktivieren Sie die Cloud Monitoring API und die Telemetry API in Ihrem Google Cloud Projekt. Achten Sie besonders auf die Telemetry API, telemetry.googleapis.com. Möglicherweise verwenden Sie diese API zum ersten Mal.

Aktivieren Sie die APIs mit den folgenden Befehlen:

gcloud services enable monitoring.googleapis.com
gcloud services enable telemetry.googleapis.com

Cluster erstellen

GKE-Cluster erstellen

  1. Erstellen Sie mit dem folgenden Befehl einen Google Kubernetes Engine-Cluster mit dem Namen otlp-test:

    gcloud container clusters create-auto --location CLUSTER_LOCATION otlp-test --project PROJECT_ID

  2. Nachdem der Cluster erstellt wurde, stellen Sie mit dem folgenden Befehl eine Verbindung zu ihm her:

    gcloud container clusters get-credentials otlp-test --region CLUSTER_LOCATION --project PROJECT_ID

Kubernetes-Dienstkonto autorisieren

Mit den folgenden Befehlen werden dem Kubernetes-Dienstkonto die erforderlichen IAM-Rollen (Identity and Access Management) zugewiesen. Bei diesen Befehlen wird davon ausgegangen, dass Sie Workload Identity Federation for GKE verwenden:

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

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/logging.logWriter \
  --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 projects/PROJECT_ID \
  --role=roles/monitoring.metricWriter \
  --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 projects/PROJECT_ID \
  --role=roles/telemetry.tracesWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

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.
  • Weisen Sie die in den vorherigen Befehlen gezeigten Rollen zu, nicht nur die Rolle roles/monitoring.metricWriter.

OpenTelemetry Collector bereitstellen

Erstellen Sie die Collector-Konfiguration, indem Sie eine Kopie der folgenden YAML-Datei erstellen und sie in einer Datei mit dem Namen collector.yaml platzieren. Sie finden die folgende Konfiguration auch auf GitHub im otlp-k8s-ingest Repository.

Ersetzen Sie in Ihrer Kopie unbedingt ${GOOGLE_CLOUD_PROJECT} durch Ihre Projekt-ID, PROJECT_ID.

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

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  # The googlecloud exporter is used for logs
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace and
  # metrics to Google Managed Prometheus using OTLP http/proto.
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  # Standard for the collector. Used for probes.
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  # This is an auth extension that adds Google Application Default Credentials to http and gRPC requests.
  googleclientauth:


processors:
  # This filter is a standard part of handling the collector's self-observability metrics. Not related to OTLP ingestion.
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count

  # The recommended batch size for the OTLP endpoint is 200 metric data points.
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The k8sattributes processor adds k8s resource attributes to metrics based on the source IP that sent the metrics to the collector.
  # k8s attributes are important for avoiding errors from timeseries "collisions".
  # These attributes help distinguish workloads from each other, and provide useful metadata (e.g. namespace) when querying.
  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  # Standard processor for gracefully degrading when overloaded to prevent OOM.
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # Standard processor for enriching self-observability metrics. Unrelated to OTLP ingestion.
  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)

  # The resourcedetection processor, similar to the k8sattributes processor, enriches metrics with important metadata.
  # The gcp detector provides the cluster name and cluster location.
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  # This transform processor avoids ingestion errors if metrics contain attributes with names that are reserved for the prometheus_target resource.
  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")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil
  # For each Prometheus unknown-typed metric, which is a gauge, create a counter that is an exact copy of this metric.
  # The GCP OTLP endpoint will add appropriate the appropriate suffixes for the counter and gauge.
  transform/unknown-counter:
    metric_statements:
    - context: metric
      statements:
      # Copy the unknown metric, but add a suffix so we can distinguish the copy from the original.
      - copy_metric(Concat([metric.name, "unknowncounter"], ":")) where metric.metadata["prometheus.type"] == "unknown" and not HasSuffix(metric.name, ":unknowncounter")
      # Change the copy to a monotonic, cumulative sum.
      - convert_gauge_to_sum("cumulative", true) where HasSuffix(metric.name, ":unknowncounter")
      # Delete the extra suffix once we are done.
      - set(metric.name, Substring(metric.name, 0, Len(metric.name)-Len(":unknowncounter"))) where HasSuffix(metric.name, ":unknowncounter")

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318

  # Push the collector's own self-observability metrics to the otlp receiver.
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    # Recieve OTLP logs, and export logs using the googlecloud exporter.
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    # Recieve OTLP metrics, and export metrics to GMP using the otlphttp exporter.
    metrics/otlp:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - transform/unknown-counter
      - metricstarttime
      - batch
      receivers:
      - otlp
    # Scrape self-observability Prometheus metrics, and export metrics to GMP using the otlphttp exporter.
    metrics/self-metrics:
      exporters:
      - otlphttp
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    # Recieve OTLP traces, and export traces using the otlphttp exporter.
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: ${env:MY_POD_IP}:14317

Bereitgestellten OpenTelemetry Collector konfigurieren

Konfigurieren Sie die Collector-Bereitstellung, indem Sie Kubernetes-Ressourcen erstellen.

  1. Erstellen Sie den Namespace opentelemetry und erstellen Sie die Collector-Konfiguration im Namespace, indem Sie die folgenden Befehle ausführen:

    kubectl create namespace opentelemetry

kubectl create configmap collector-config -n opentelemetry --from-file=collector.yaml

  2. Konfigurieren Sie den Collector mit Kubernetes-Ressourcen, indem Sie die folgenden Befehle ausführen:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/2_rbac.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/3_service.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/4_deployment.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/5_hpa.yaml

  3. Warten Sie, bis die Collector-Pods den Status „Running“ erreicht haben und 1/1 Container bereit sind. Das dauert bei Autopilot etwa drei Minuten, wenn dies die erste bereitgestellte Arbeitslast ist. Verwenden Sie den folgenden Befehl, um die Pods zu prüfen:

    kubectl get po -n opentelemetry -w

    Geben Sie Strg + C ein, um den Befehl zu beenden und den Pod-Status nicht mehr zu beobachten.

  4. Sie können auch die Collector-Logs prüfen, um sicherzugehen, dass keine offensichtlichen Fehler vorliegen:

    kubectl logs -n opentelemetry deployment/opentelemetry-collector

Telemetriegenerator bereitstellen

Sie können Ihre Konfiguration mit dem Open-Source telemetrygen Tool testen. Diese App generiert Telemetriedaten und sendet sie an den Collector.

  1. Führen Sie den folgenden Befehl aus, um die App telemetrygen im Namespace opentelemetry-demo bereitzustellen:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/main/sample/app.yaml

  2. Nachdem Sie die Bereitstellung erstellt haben, kann es einige Zeit dauern, bis die Pods erstellt und ausgeführt werden. Führen Sie den folgenden Befehl aus, um den Status der Pods zu prüfen:

    kubectl get po -n opentelemetry-demo -w

    Geben Sie Strg + C ein, um den Befehl zu beenden und den Pod-Status nicht mehr zu beobachten.

Messwert mit dem Metrics Explorer abfragen

Das telemetrygen Tool schreibt in einen Messwert mit dem Namen gen. Sie können diesen Messwert sowohl über die Abfrageerstellungsoberfläche als auch über den PromQL-Abfrageeditor im Metrics Explorer abfragen.

Rufen Sie in der Google Cloud Console das  Metrics Explorer auf:

Zu Metrics Explorer

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

  • Wenn Sie die Abfrageerstellungsoberfläche des Metrics Explorer verwenden, lautet der vollständige Name des Messwerts prometheus.googleapis.com/gen/gauge.
  • Wenn Sie den PromQL-Abfrageeditor verwenden, können Sie den Messwert mit dem Namen gen abfragen.

Die folgende Abbildung zeigt ein Diagramm des Messwerts gen im Metrics Explorer:

Ein Diagramm zeigt den Messwert „gen“, der vom OTLP-HTTP-Exporter erfasst wird.

Cluster löschen

Nachdem Sie Ihre Bereitstellung durch Abfragen des Messwerts überprüft haben, können Sie den Cluster löschen. Führen Sie den folgenden Befehl aus, um den Cluster zu löschen:

gcloud container clusters delete --location CLUSTER_LOCATION otlp-test --project PROJECT_ID

Andere OpenTelemetry-basierte Collectors verwenden

Möglicherweise können Sie andere OpenTelemetry-basierte Collectors verwenden, um OTLP Messwerte an die Telemetry API zu senden. bietet jedoch keinen Kundensupport für nicht standardmäßige OpenTelemetry-basierte Collectors. Google Cloud

Sie können beispielsweise Messwerte mit Grafana Alloy Version 1.16.0 oder höher senden, indem Sie sich mit der otelcol.auth.google Komponente authentifizieren und sie ähnlich wie einen Standard-OpenTelemetry Collector konfigurieren. Folgen Sie dazu der Anleitung in diesem Dokument.

Nächste Schritte