Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Verwaltetes OpenTelemetry für GKE bereitstellen

Autopilot Standard

In diesem Dokument wird beschrieben, wie Sie Managed OpenTelemetry für GKE einrichten, um OpenTelemetry Protocol (OTLP)-Traces, ‑Messwerte und ‑Logs von Anwendungen, die in GKE ausgeführt werden, an Google Cloud Observability zu senden.

Weitere Informationen zur Funktionsweise von Managed OpenTelemetry für GKE finden Sie unter Managed OpenTelemetry für GKE.

Mit Managed OpenTelemetry für GKE haben Sie folgende Möglichkeiten:

Konfigurieren Sie Arbeitslasten, die in GKE ausgeführt werden, so, dass Traces, Messwerte und Logs von OpenTelemetry Protocol (OTLP) an den verwalteten Collector gesendet werden.
Empfangen Sie OTLP-Traces, ‑Messwerte und ‑Logs (OpenTelemetry Protocol) von den Anwendungen, die in GKE ausgeführt werden.
Exportieren Sie diese Daten nach Google Cloud Observability.

Wenn Sie Filterung und Steuerelemente auf Collector-Ebene benötigen, verwenden Sie stattdessen den von Google entwickelten OpenTelemetry Collector.

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

Installieren Sie die Google Cloud CLI.

Hinweis:Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die aktuelle Version haben, indem Sie gcloud components update ausführen.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

So erstellen Sie ein Google Cloud -Projekt:
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.
Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die GKE-, Telemetry (OTLP)-, Cloud Logging-, Cloud Monitoring- und Cloud Trace APIs:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Installieren Sie die Google Cloud CLI.

Hinweis:Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die aktuelle Version haben, indem Sie gcloud components update ausführen.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

So erstellen Sie ein Google Cloud -Projekt:
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.
Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Aktivieren Sie die GKE-, Telemetry (OTLP)-, Cloud Logging-, Cloud Monitoring- und Cloud Trace APIs:

Rollen, die zum Aktivieren von APIs erforderlich sind

gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Voraussetzungen

Um Managed OpenTelemetry für GKE zu verwenden, müssen Sie die folgenden Anforderungen erfüllen:

Der Cluster muss die GKE-Version 1.34.1-gke.2178000 oder höher haben.
gcloud CLI mit Version 551.0.0 oder höher.
Wenn Sie Terraform zum Bereitstellen Ihrer GKE-Infrastruktur verwenden, müssen Sie den terraform-provider-google-beta-Anbieter in Version v7.17.0 oder höher verwenden.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aktivieren und Verwenden von GKE Managed OpenTelemetry benötigen:

Administrator für Kubernetes Engine-Cluster (roles/container.clusterAdmin)
Monitoring Viewer (roles/monitoring.viewer)
Loganzeige (roles/logging.viewer)
Cloud Trace User (roles/cloudtrace.user)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Kosten

Weitere Informationen zu den Kosten für die Verwendung von Managed OpenTelemetry für GKE finden Sie unter Abrechnung.

Verwaltetes OpenTelemetry für GKE in einem Cluster aktivieren

So richten Sie Managed OpenTelemetry für GKE ein:

Verwaltetes OpenTelemetry für GKE in einem Cluster aktivieren.
Konfigurieren Sie die Anwendung, die Sie überwachen, so, dass Signale an den Endpunkt des verwalteten Collectors gesendet werden.

Wenn Sie verwaltetes OpenTelemetry für GKE aktivieren, werden die folgenden Objekte im Cluster bereitgestellt:

Eine GKE Managed OpenTelemetry Collector-Bereitstellung, die im Namespace gke-managed-otel bereitgestellt wird. Der HTTP-Endpunkt des verwalteten OpenTelemetry Collectors im Cluster für Logs, Messwerte und Traces ist: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.
Eine benutzerdefinierte Ressourcendefinition (Custom Resource Definition, CRD) instrumentations.telemetry.googleapis.com, mit der Sie die automatische Konfiguration Ihrer Arbeitslasten einrichten können.

Weitere Informationen zu benutzerdefinierten Ressourcen finden Sie in der Kubernetes-Dokumentation unter Benutzerdefinierte Ressource.

In einem neuen Cluster aktivieren

So aktivieren Sie verwaltetes OpenTelemetry für GKE in einem neuen Cluster:

gcloud

Verwenden Sie für einen Autopilot-Cluster den folgenden Befehl:

gcloud beta container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Ersetzen Sie Folgendes:

CLUSTER_NAME ist der Name des Clusters.
PROJECT_ID: die Google Cloud Projekt-ID.
LOCATION: die Region oder Zone.
VERSION: Die Version, die 1.34.1-gke.2178000 oder höher sein muss.

Verwenden Sie für einen Standardcluster den folgenden Befehl:

gcloud beta container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Ersetzen Sie Folgendes:

CLUSTER_NAME ist der Name des Clusters.
PROJECT_ID: die Google Cloud Projekt-ID.
LOCATION: die Region oder Zone.
VERSION: Die Version, die 1.34.1-gke.2178000 oder höher sein muss.

Console

Führen Sie für einen Autopilot-Cluster die folgenden Schritte aus:
1. Rufen Sie in der Google Cloud Console die Seite Autopilot-Cluster erstellen auf.
  Zur Seite „Autopilot-Cluster erstellen“
2. Klicken Sie im Navigationsbereich auf Erweiterte Einstellungen.
3. Wählen Sie im Abschnitt Vorgänge die Option Verwaltetes OpenTelemetry aktivieren aus.
4. Klicken Sie auf Speichern.
Führen Sie für einen Standardcluster die folgenden Schritte aus:
1. Rufen Sie in der Google Cloud Console die Seite Kubernetes-Cluster erstellen auf.
  Zur Seite „Kubernetes-Cluster erstellen“
2. Klicken Sie im Navigationsbereich auf Features.
3. Wählen Sie im Abschnitt Vorgänge die Option Verwaltetes OpenTelemetry aktivieren aus.
4. Klicken Sie auf Speichern.

Terraform

Informationen zum Aktivieren von verwaltetem OpenTelemetry für GKE in einem neuen Cluster mit Terraform finden Sie im folgenden Beispiel:

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Weitere Informationen zur Verwendung von Terraform finden Sie unter Terraform-Unterstützung für GKE.

Für einen vorhandenen Cluster aktivieren

So aktivieren Sie Managed OpenTelemetry für GKE in einem vorhandenen Cluster:

gcloud

Achten Sie darauf, dass die Clusterversion 1.34.1-gke.2178000 oder höher ist. Weitere Informationen zum Upgraden eines vorhandenen Clusters finden Sie unter Upgrade von Standardclustern und Upgrade von Autopilot-Clustern.
Aktivieren Sie verwaltetes OpenTelemetry für GKE mit dem folgenden Befehl:
```
gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION
```
Ersetzen Sie Folgendes:
- CLUSTER_NAME ist der Name des Clusters.
- PROJECT_ID: die Google Cloud Projekt-ID.
- LOCATION: die Region oder Zone.

Console

Achten Sie darauf, dass die Clusterversion 1.34.1-gke.2178000 oder höher ist. Weitere Informationen zum Upgraden eines vorhandenen Clusters finden Sie unter Upgrade von Standardclustern und Upgrade von Autopilot-Clustern.
Rufen Sie in der Google Cloud Console die Seite „Kubernetes-Cluster“ auf:

Zur Seite "Kubernetes-Cluster"
Klicken Sie auf den Namen des Clusters.
Suchen Sie in der Liste Features die Option Verwaltetes OpenTelemetry. Wenn es als deaktiviert aufgeführt ist, klicken Sie auf Bearbeiten und wählen Sie dann Verwaltetes OpenTelemetry aktivieren aus.
Klicken Sie auf Änderungen speichern.

Terraform

Wenn Sie Managed OpenTelemetry für GKE in einem vorhandenen Cluster aktivieren möchten, fügen Sie den managed_opentelemetry_config-Block Ihrer vorhandenen google_container_cluster-Ressource hinzu, wie im folgenden Beispiel:

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Weitere Informationen zur Verwendung von Terraform finden Sie unter Terraform-Unterstützung für GKE.

Anwendung für die Verwendung des verwalteten OpenTelemetry Collectors konfigurieren

Anwendungen müssen so konfiguriert werden, dass sie Signale an den Endpunkt des verwalteten Collectors senden können. Wenn die Anwendungen konfiguriert sind, empfängt der verwaltete OpenTelemetry-Collector Signale von den Anwendungen, die auf dem Cluster ausgeführt werden, auf dem der Collector aktiviert ist. Signale aus der Anwendung umfassen Traces, Messwerte und Logs.

Damit OpenTelemetry-Signale gesendet werden können, müssen Anwendungen bereits instrumentiert sein, um OpenTelemetry-Messwerte zu generieren. Weitere Informationen finden Sie unter Unterstützte Arbeitslasten.

Sie können Ihre Anwendung manuell konfigurieren, um Signale an den Endpunkt des verwalteten Collectors zu senden, oder die automatische Konfiguration verwenden. Wir empfehlen nicht, beide Methoden für dieselbe Arbeitslast zu verwenden, da die automatische Konfiguration manuelle Änderungen überschreiben kann. Diese Kombination kann es erschweren, Änderungen an der Konfiguration nachzuvollziehen.

In den folgenden Abschnitten wird beschrieben, wie Sie Anwendungen so konfigurieren, dass sie mithilfe der automatischen Konfiguration Signale an den Collector senden.

Automatische Konfiguration einrichten

Bei der automatischen Konfiguration werden Umgebungsvariablen verwendet, um die Arbeitslasten so zu konfigurieren, dass Signale an den Endpunkt des verwalteten Collectors gesendet werden.

Wenn Sie die automatische Einfügung von Umgebungsvariablen in Pods aktivieren möchten, verwenden Sie die benutzerdefinierte Ressource Instrumentation. Die Umgebungsvariablen enthalten die OpenTelemetry-Konfiguration und können in einige Pods mit übereinstimmenden Labels in einem Namespace oder in alle Pods in einem Namespace eingefügt werden.

Wenn eine Anwendung dann im Namespace bereitgestellt wird, verwendet GKE die Konfiguration, um automatisch Umgebungsvariablen in die Pods einzufügen, in denen die Arbeitslasten ausgeführt werden.

So konfigurieren Sie die benutzerdefinierte Ressource Instrumentation:
1. Speichern Sie das folgende Instrumentation-Manifest in einer Datei mit dem Namen otlp-auto-config-namespace.yaml:
```
apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
```
  Ersetzen Sie Folgendes:
  - NAMESPACE: Der Namespace, der die Pods enthält, die für die automatische Instrumentierung verwendet werden sollen. Verwenden Sie default, um den Standard-Namespace als Ziel festzulegen.
  - NAME: der Name der Manifestdatei. In diesem Beispiel lautet der Name otlp-auto-config-namespace.yaml.
  - Optional: Das Label, das an Pods angehängt ist, auf die ausgerichtet werden soll. Wenn ein leerer Selektor angegeben wird ({}), werden alle Pods im Namespace als Ziel festgelegt.
    - KEY: der Schlüssel des Labels
    - VALUE: der Wert des Labels
  - TRACE_RATIO: Das Verhältnis der zu erfassenden Trace-Daten. Wenn nicht angegeben, ist der Standardwert 1.0. Weitere Informationen finden Sie unter Abtastrate für Traces ändern.
  - METRICS_INTERVAL: Das Intervall in Millisekunden, in dem Überwachungsdaten erfasst werden sollen. Der Standardwert ist 30000. Der Wert muss nicht negativ sein, mit einem Minimum von 5.000 ms, einem Maximum von 300.000 ms und einem Vielfachen von 5.000 ms. Weitere Informationen finden Sie unter Messwertexportintervall ändern.
2. Wenn Sie eine der Einstellungen ändern möchten, lesen Sie den folgenden Abschnitt zum Ändern der Konfiguration.
3. Wenden Sie die Konfiguration mit dem folgenden Befehl an:
```
kubectl apply -f otlp-auto-config-namespace.yaml
```
Damit die Umgebungsvariablen automatisch eingefügt werden, müssen Sie die Anwendung in dem Namespace in Ihrem Cluster bereitstellen, auf den die Konfiguration angewendet wird.
- Wenn Sie die Konfiguration auf eine Arbeitslast anwenden möchten, die noch nicht im Namespace ausgeführt wird, stellen Sie die Arbeitslast mit dem folgenden Befehl bereit:
```
kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE
```
  Ersetzen Sie Folgendes:
  - DEPLOYMENT_NAME: Der Name der Bereitstellung.
  - NAMESPACE: der Namespace.
- Wenn Sie die Konfiguration auf eine Arbeitslast anwenden möchten, die bereits im Namespace ausgeführt wird, stellen Sie die Arbeitslast mit dem folgenden Befehl noch einmal bereit:
```
kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE
```
  Ersetzen Sie Folgendes:
  - DEPLOYMENT_NAME: Der Name der Bereitstellung.
  - NAMESPACE: der Namespace.

Nachdem Sie die Konfiguration auf den Cluster angewendet haben, konfiguriert GKE alle Arbeitslasten automatisch, wenn sie im Cluster bereitgestellt werden. Die Arbeitslasten werden instrumentiert, indem Umgebungsvariablen in die Pods eingefügt werden, in denen die Arbeitslasten ausgeführt werden.

Wenn eine Arbeitslast, die mit diesen Umgebungsvariablen konfiguriert ist, in einem Cluster ausgeführt wird, in dem der verwaltete Collector bereitgestellt ist, werden während der Ausführung der Arbeitslast OpenTelemetry-Signale an den verwalteten Collector gesendet. Diese Signale sind in Google Cloud Observability verfügbar.

Weitere Informationen zum Anzeigen der Signale finden Sie unter Telemetriedaten ansehen. Ein Beispiel finden Sie unter Beispieltelemetrie generieren.

Konfiguration ändern

So ändern Sie die Konfiguration:

Ändern Sie die Manifestdatei Instrumentation.
Wenden Sie die geänderte Konfiguration an.
Stellen Sie die Anwendungen im entsprechenden Namespace Ihres Clusters nach der Anwendung der geänderten Konfiguration noch einmal bereit oder starten Sie sie neu.

Weitere Informationen zu diesen Schritten finden Sie im Abschnitt Konfiguration erstellen und bereitstellen.

Menge oder Häufigkeit der Datenerhebung ändern

Sie können die Menge der erfassten Trace-Daten durch Ändern der Trace-Abtastrate anpassen.

Sie können die Häufigkeit ändern, mit der Monitoring-Daten an Cloud Monitoring gesendet werden, indem Sie das Messwert-Exportintervall ändern.

Sie können die Menge oder Häufigkeit der erfassten Logging-Daten nicht ändern. Sie können jedoch die Erfassung aller Logging-, Messwert- oder Tracing-Daten deaktivieren. Weitere Informationen finden Sie unter Signaltyp für die Erfassung auswählen.

Trace-Sampling-Rate ändern

Eine Arbeitslast kann eine große Menge an Trace-Daten generieren. Für Ihre eigene Situation ist es wichtig, dass Sie das richtige Verhältnis zwischen den Kosten für das Erheben und Speichern von Daten und dem Detaillierungsgrad bestimmen, der erforderlich ist, damit die Daten nützlich sind.

Das Standardverhalten des OpenTelemetry SDK ist always_on, was einem Verhältnis von 1 entspricht.

Im Folgenden sehen Sie ein Beispiel für die Konfiguration der Trace-Stichprobenrate. In diesem Beispiel beträgt das Verhältnis 0, 25.Die Trace-Daten werden also mit einer Rate von 25 % erfasst. Ändern Sie diese Verhältniszahl, um die Stichprobenrate zu ändern.

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

Messwertexportintervall ändern

Das Messwert-Exportintervall bestimmt den Detaillierungsgrad der Daten, die in den Diagrammen in Cloud Monitoring angezeigt werden.

Im Folgenden sehen Sie ein Beispiel für die Konfiguration des Intervalls für den Metrikexport. In diesem Beispiel beträgt das Exportintervall 30.000 ms.

Mit dem Messwert-Exportintervall wird das Verzögerungsintervall zwischen dem Start von zwei aufeinanderfolgenden Exporten von Messwerten aus dem OpenTelemetry SDK angegeben.

Der Wert dieses Intervalls muss nicht negativ sein, mit einem Minimum von 5.000 ms, einem Maximum von 300.000 ms und einem Vielfachen von 5.000 ms. Der Wert wird in Millisekunden angegeben.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Signaltypen auswählen, die erfasst werden sollen

Sie können festlegen, welche Signaltypen für eine Arbeitslast erfasst werden, indem Sie die Signaltypen deaktivieren, die nicht erfasst werden sollen. Signaltypen sind Traces, Messwerte und Logs.

Sie deaktivieren Signaltypen mit den Umgebungsvariablen im Container, in dem die Arbeitslast ausgeführt wird. Sie ändern Umgebungsvariablen, indem Sie die benutzerdefinierte Ressource Instrumentation ändern und die Arbeitslast dann im Container neu bereitstellen.

Das folgende Beispiel zeigt eine Instrumentation-Manifestdatei, die für die Erfassung von Tracedaten konfiguriert ist. Die Erfassung von Protokollen und Messwerten ist deaktiviert, weil meter_provider und logger_provider auf null festgelegt sind.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

Erfassung von Daten zu multimodalen Prompts und Antworten

Sie können Managed OpenTelemetry für GKE so konfigurieren, dass Daten zu multimodalen Prompts und Antworten erfasst werden.

Diese Funktion ist für LangGraph ReAct-Agenten und generative KI-Agenten verfügbar, die mit dem Agent Development Kit (ADK)-Framework erstellt wurden.

So konfigurieren Sie Managed OpenTelemetry für GKE, um Daten zu multimodalen Prompts und Antworten zu erfassen:

Konfigurieren Sie Ihr Google Cloud -Projekt und das verwendete SDK gemäß der Anleitung im Abschnitt Multimodale Prompts und Antworten erfassen.
Erstellen oder identifizieren Sie einen Cloud Storage-Bucket, in dem multimodale Prompts und Antworten gespeichert werden sollen. Weitere Informationen finden Sie unter Bucket erstellen.
Gewähren Sie dem Dienstkonto, das Ihre Anwendung verwendet, die Berechtigung storage.objects.create für den Cloud Storage-Bucket.

Mit dieser Berechtigung kann Ihre Anwendung Objekte in den Cloud Storage-Bucket schreiben. In diesen Objekten werden die Prompts und Antworten gespeichert, die von der agentischen Anwendung erstellt und empfangen werden. Weitere Informationen finden Sie unter IAM-Richtlinien für Buckets festlegen und verwalten.

Konfigurieren Sie das Feld promptsResponses.uploadBasePath in der benutzerdefinierten Ressource Instrumentation, z. B.:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

Ersetzen Sie BUCKET_NAME durch den Namen des Cloud Storage-Bucket.

Wenn die benutzerdefinierte Ressource Instrumentation aktualisiert und die Arbeitslasten neu gestartet werden, werden Umgebungsvariablen, die die Prompts und Antworten konfigurieren, in die Container der Arbeitslasten eingefügt.

Weitere Informationen zu den Arten von Media, die Sie erfassen können, und dazu, wie Sie Ihre multimodalen Prompts und Antworten untersuchen, finden Sie unter Multimodale Prompts und Antworten erfassen und ansehen.

Automatische Konfiguration von Arbeitslasten deaktivieren

Wenn Sie die automatische Instrumentierung von Arbeitslasten mit der angegebenen Konfiguration deaktivieren möchten, löschen Sie die benutzerdefinierte Ressource Instrumentation aus Ihrem Cluster. Verwenden Sie dazu den folgenden Befehl:

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

Ersetzen Sie Folgendes:

INSTRUMENTATION_NAME: der Name der benutzerdefinierten Ressource Instrumentation.
NAMESPACE: der Namespace, der die Pods enthält, für die die automatische Konfiguration deaktiviert werden soll.

Wenn Sie die automatische Einfügung von Umgebungsvariablen vorübergehend deaktivieren und gleichzeitig die Konfiguration der automatischen Instrumentierung für die zukünftige Verwendung beibehalten möchten, setzen Sie autoInstrumentationConfig.configInjection.enabled auf false und wenden Sie die aktualisierte benutzerdefinierte Ressource an.

Hier ein Beispiel für die benutzerdefinierte Ressource, bei der die automatische Einfügung von Umgebungsvariablen vorübergehend deaktiviert ist:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

Nachdem Sie die benutzerdefinierte Ressource gelöscht oder aktualisiert haben, um die automatische Konfiguration zu deaktivieren, instrumentiert GKE keine neuen Arbeitslasten mehr, die auf die benutzerdefinierte Ressource Instrumentation ausgerichtet sind.

Wenn Sie den Export von OTLP-Signalen an den verwalteten Collector aus einer Arbeitslast beenden möchten, die zuvor von der benutzerdefinierten Ressource instrumentiert wurde, müssen Sie die Arbeitslast neu starten, damit die Änderung wirksam wird. Verwenden Sie dazu den folgenden Befehl:

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

Ersetzen Sie Folgendes:

DEPLOYMENT_NAME: Der Name der Bereitstellung.
NAMESPACE: der Namespace.

Telemetriedaten ansehen

Wenn eine konfigurierte Arbeitslast in GKE ausgeführt wird und Managed OpenTelemetry für GKE aktiviert ist, werden OpenTelemetry-Signale an Google Cloud Observability gesendet.

Weitere Informationen zum Ansehen von Daten in Google Cloud Observability finden Sie unter:

Beispieltelemetrie generieren

In diesem Abschnitt wird beschrieben, wie Sie eine Beispielanwendung bereitstellen und auf den OTLP-Endpunkt des verwalteten OpenTelemetry Collectors verweisen. Anschließend können Sie die Telemetrie in Google Cloud ansehen.

Die Beispielanwendung ist ein kleiner Generator, der Traces, Logs und Messwerte an den HTTP-Endpunkt des verwalteten OpenTelemetry Collectors im Cluster exportiert. Der OTLP-Endpunkt ist in der Anwendung fest codiert und verweist auf http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

Wenn Sie bereits eine Anwendung mit einem OpenTelemetry SDK instrumentiert haben, können Sie Telemetriedaten aus Ihrer Anwendung generieren, indem Sie Ihre Anwendung auf den Endpunkt des Collectors verweisen oder die automatische Instrumentierung für die Anwendung konfigurieren.

So stellen Sie die Beispielanwendung bereit:

Stellen Sie eine Verbindung zu Ihrem Cluster her, in dem Sie verwaltetes OpenTelemetry aktiviert haben. Weitere Informationen finden Sie unter Standardcluster für Befehle vom Typ kubectl festlegen.
Führen Sie dazu diesen Befehl aus:
```
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml
```
Nach einigen Minuten beginnt die von der Anwendung generierte Telemetrie, für jedes Signal durch den Collector an das Google Cloud -Backend zu fließen.
1. Prüfen Sie, ob die Telemetrie erfasst wird, indem Sie sich Logs, Messwerte und Traces der Demoanwendung in der Google Cloud Console ansehen:
2. So rufen Sie Messwerte auf:
  1. Rufen Sie in der Google Cloud Console die Seite „Metrics Explorer“ auf:
    
    Zum Metrics Explorer
  2. Führen Sie die folgende PromQL-Abfrage im Metrics Explorer aus:
```
sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))
```
3. So rufen Sie Traces auf:
  1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf.
    
    Zum Trace Explorer
  2. Trace-Spans nach dem Namen des Spans filtern, der gleich lets-go ist.
4. So rufen Sie Logs auf:
  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.
    
    Zum Log-Explorer
  2. Führen Sie die folgende Abfrage aus:
```
resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"
```

Verwaltetes OpenTelemetry für GKE deaktivieren

Sie können verwaltetes OpenTelemetry für GKE im Cluster deaktivieren. Wenn Sie den Collector deaktivieren, wird der verwaltete OpenTelemetry Collector aus dem Cluster entfernt und es werden keine neuen Telemetriedaten mehr erfasst.

So deaktivieren Sie Managed OpenTelemetry für GKE:

gcloud

Führen Sie den folgenden gcloud-Befehl aus, um Managed OpenTelemetry für GKE für einen Cluster zu deaktivieren:

  gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

Ersetzen Sie Folgendes:

CLUSTER_NAME ist der Name des Clusters.
PROJECT_ID: die Google Cloud Projekt-ID.
LOCATION: die Region oder Zone.

Console

Rufen Sie in der Console die Liste der Cluster auf:

Zur Seite "Kubernetes-Cluster"
Wählen Sie den Cluster aus, für den Sie den verwalteten OpenTelemetry-Collector deaktivieren möchten.
Wählen Sie unter Clusterdetails neben Verwaltetes OpenTelemetry das Bearbeitungssymbol aus.
Entfernen Sie das Häkchen, um die Funktion zu deaktivieren.

Terraform

Wenn Sie Managed OpenTelemetry für GKE deaktivieren möchten, aktualisieren Sie den managed_opentelemetry_config-Block in Ihrer google_container_cluster-Ressource, um den Bereich auf NONE festzulegen.

Aktualisieren Sie Ihre Terraform-Konfigurationsdatei:

resource "google_container_cluster" "default" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

Wenden Sie die Terraform-Konfiguration an:
```
terraform apply
```

Ersetzen Sie Folgendes:

CLUSTER_NAME ist der Name des Clusters.
LOCATION: die Region oder Zone.
PROJECT_ID: die Google Cloud Projekt-ID.

Wenn Sie Managed OpenTelemetry für GKE deaktivieren, werden die benutzerdefinierte Ressourcendefinition Instrumentation und die benutzerdefinierten Ressourcen Instrumentation nicht aus dem Cluster entfernt. Wenn Sie verwaltetes OpenTelemetry wieder aktivieren, wird die in den benutzerdefinierten Instrumentation-Ressourcen gespeicherte Konfiguration verwendet.

Wenn Sie bereits Telemetriedaten haben, die von Managed OpenTelemetry für GKE erfasst wurden, hat das Deaktivieren des Collectors keine Auswirkungen auf diese Daten. Vorhandene Daten werden weiterhin in Google Cloud Observability gespeichert und es werden keine neuen Telemetriedaten erhoben.

Fehlerbehebung

Privilegierte Autopilot-Partnerarbeitslasten

Wenn Sie versuchen, die automatische Konfiguration mit einer privilegierten Arbeitslast eines Autopilot-Partners zu verwenden, wird der Pod für diese Arbeitslast möglicherweise abgelehnt.

Die OpenTelemetry-Konfigurationsinjektion wird für privilegierte Arbeitslasten von GKE Autopilot-Partnern nicht unterstützt. Wenn Sie solche Arbeitslasten mit einer benutzerdefinierten Instrumentation-Ressource anvisieren, um die OpenTelemetry-Umgebungsvariableninjektion zu aktivieren, kann es sein, dass die Arbeitslast nicht mit der Zulassungsliste für privilegierte Autopilot-Arbeitslasten übereinstimmt. Das bedeutet, dass der mit der Konfiguration injizierte Pod von GKE Autopilot abgelehnt wird.

Logs, Messwerte oder Traces sind in der Google Cloud Console nicht sichtbar

Es gibt viele verschiedene Gründe, warum Daten möglicherweise nicht sichtbar sind. Dazu gehören fehlende Berechtigungen zum Aufrufen der Daten oder eine falsche Konfiguration, die verhindert, dass Daten erhoben werden.

So können Sie häufige Probleme beheben:

Prüfen Sie, ob alle erforderlichen APIs in Ihrem Projekt aktiviert sind.
Achten Sie darauf, dass die benutzerdefinierte Instrumentation-Ressource richtig konfiguriert ist. Der Namespace muss mit dem Namespace übereinstimmen, in dem die Arbeitslast ausgeführt wird, und der Selektor muss mit dem Label Ihrer Arbeitslast übereinstimmen.
Prüfen Sie den Pod der Arbeitslast, um festzustellen, ob die Umgebungsvariablen richtig eingefügt wurden.
Prüfen Sie die Containerlogs des OpenTelemetry Collector, um festzustellen, ob Fehler im Collector vorliegen. Dazu führen Sie den folgenden Befehl aus:
```
kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector
```

Deaktivieren eines Telemetriesignals funktioniert nicht

Wenn Sie ein Telemetriesignal mit der benutzerdefinierten Ressource Instrumentation deaktivieren, müssen Sie die benutzerdefinierte Ressource anwenden und die Arbeitslasten neu bereitstellen.

Verwenden Sie beim Anwenden der benutzerdefinierten Ressource Server-Side Apply im Befehl kubectl apply, wenn Sie die benutzerdefinierte Ressource Instrumentation aktualisieren.

Weitere Informationen zum Deaktivieren eines Telemetriesignals finden Sie unter Signaltypen für die Erfassung auswählen.

In meinen Arbeitslasten sind keine OpenTelemetry-Variablen sichtbar.

Die Variablen werden in die Container der Arbeitslast-Pods und nicht in die Arbeitslast eingefügt. Prüfen Sie die Pods, nicht die zugehörigen Objekte wie ReplicaSets oder Deployments.

So prüfen Sie beispielsweise, ob die Variablen für die Beispielarbeitslast im Standard-Namespace, die im vorherigen Abschnitt Telemetrie generieren verwendet wurde, korrekt eingefügt wurden:

Führen Sie dazu diesen Befehl aus:

kubectl get pods -n default -l app=telemetrygen-app -o yaml

Prüfen Sie die spec.containers[*].env der Pods.
Prüfen Sie, ob ein Instrumentation-Objekt im selben Namespace vorhanden ist, und ob es auf den Pod ausgerichtet ist und die Funktion zum Einfügen von Konfigurationen aktiviert ist. Dazu führen Sie den folgenden Befehl aus:
```
kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml
```

Die Variablen werden nur beim Erstellen von Pods in die Container eingefügt, da die meisten Felder in der Spezifikation eines vorhandenen Pods, z. B. Umgebungsvariablen, über die Kubernetes API nicht geändert werden können. Damit die Konfiguration für Arbeitslasten wirksam wird, die vor der Erstellung des Instrumentation-Objekts erstellt wurden, müssen Sie die Arbeitslast neu starten. Führen Sie beispielsweise für ein Deployment mit dem Namen telemetry-gen-app den folgenden Befehl aus:

kubectl rollout restart deployment -n default telemetry-gen-app

Eine übermäßige Menge an Trace-Daten in Cloud Trace

Um die von Cloud Trace erfassten Daten zu reduzieren, können Sie einen übergeordneten Sampler mit einem Trace-ID-Verhältnis konfigurieren, um nur einen Prozentsatz Ihrer Traces zu erfassen.

Fügen Sie beispielsweise Folgendes zum Objekt Instrumentation hinzu:

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

Das Standardverhalten des OpenTelemetry SDK ist das Tracing „always_on“, was einem Verhältnis von 1 entspricht.

Umgebungsvariablen stimmen nicht mit der Konfiguration überein

Wenn Sie das Instrumentation-Objekt aktualisiert haben, starten Sie die Pods neu, wie im Abschnitt Konfiguration ändern beschrieben.

Wenn Sie die falsche Konfiguration für Ihren Pod sehen, prüfen Sie, ob der Pod korrekt auf das Instrumentation-Objekt ausgerichtet ist und ob mehrere Instrumentation-Objekte auf denselben Pod ausgerichtet sind:

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

Ein leerer Selector richtet sich an alle Pods im Namespace.

Wenn mehrere Instrumentierungen auf denselben Pod ausgerichtet sind, wenn er erstellt wird, wird die zuletzt aktualisierte Instrumentierung wirksam.

Der Befehl `kubectl logs` gibt keine Ausgabe zurück.

Wenn Logs direkt von einer Anwendung an einen OpenTelemetry Collector gestreamt werden, umgehen sie den Standard-Logging-Pfad für die Container-Laufzeit. Dies ist das gängige Szenario bei der Verwendung von OpenTelemetry für Logs. Standardmäßig sendet der Exporter die Logs an den Endpunkt otlp anstelle der Streams stdout und stderr.

Da die Logs in diesem Fall nicht in die Streams stdout oder stderr geschrieben werden, die von der Containerlaufzeit erfasst werden, wird mit dem Befehl kubectl logs keine Ausgabe für diese Anwendung angezeigt. Stattdessen ist die Logging-Ausgabe in Cloud Logging verfügbar.

Wenn Sie das OpenTelemetry SDK verwenden und auch Logs an den stdout-Stream senden möchten, können Sie dies mit dem Logs-Exporter konfigurieren. Weitere Informationen finden Sie unter Logs Exporter – Standardausgabe.

Nächste Schritte

Weitere Informationen zur Funktionsweise von Managed OpenTelemetry für GKE finden Sie unter Managed OpenTelemetry für GKE.
Eine selbst bereitgestellte Alternative zu verwaltetem OpenTelemetry für GKE finden Sie unter Von Google entwickelter OpenTelemetry Collector.

Verwaltetes OpenTelemetry für GKE bereitstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Voraussetzungen

Erforderliche Rollen

Kosten

Verwaltetes OpenTelemetry für GKE in einem Cluster aktivieren

In einem neuen Cluster aktivieren

gcloud

Console

Terraform

Für einen vorhandenen Cluster aktivieren

gcloud

Console

Terraform

Anwendung für die Verwendung des verwalteten OpenTelemetry Collectors konfigurieren

Automatische Konfiguration einrichten

Konfiguration ändern

Menge oder Häufigkeit der Datenerhebung ändern

Trace-Sampling-Rate ändern

Messwertexportintervall ändern

Signaltypen auswählen, die erfasst werden sollen

Erfassung von Daten zu multimodalen Prompts und Antworten

Automatische Konfiguration von Arbeitslasten deaktivieren

Telemetriedaten ansehen

Beispieltelemetrie generieren

Verwaltetes OpenTelemetry für GKE deaktivieren

gcloud

Console

Terraform

Fehlerbehebung

Privilegierte Autopilot-Partnerarbeitslasten

Logs, Messwerte oder Traces sind in der Google Cloud Console nicht sichtbar

Deaktivieren eines Telemetriesignals funktioniert nicht

In meinen Arbeitslasten sind keine OpenTelemetry-Variablen sichtbar.

Eine übermäßige Menge an Trace-Daten in Cloud Trace

Umgebungsvariablen stimmen nicht mit der Konfiguration überein

Der Befehl kubectl logs gibt keine Ausgabe zurück.

Nächste Schritte

Verwaltetes OpenTelemetry für GKE bereitstellen

Der Befehl `kubectl logs` gibt keine Ausgabe zurück.