Esegui il deployment di OpenTelemetry gestito per GKE

Questo documento spiega come configurare OpenTelemetry gestito per GKE per inviare tracce, metriche e log OpenTelemetry Protocol (OTLP) a Google Cloud Observability da applicazioni in esecuzione su GKE.

Per ulteriori dettagli sul funzionamento di Managed OpenTelemetry per GKE, consulta Managed OpenTelemetry per GKE.

Puoi utilizzare Managed OpenTelemetry per GKE per:

  • Configura i carichi di lavoro in esecuzione su GKE per inviare tracce, metriche e log OpenTelemetry Protocol (OTLP) al collettore gestito.
  • Ricevi tracce, metriche e log OpenTelemetry Protocol (OTLP) dalle applicazioni in esecuzione su GKE.
  • Esporta questi dati in Google Cloud Observability.

Se hai bisogno di filtri e controlli a livello di raccoglitore, utilizza Google-Built OpenTelemetry Collector anziché questa offerta gestita.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. Installa Google Cloud CLI.

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  5. Crea o seleziona un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Creare un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  6. Verifica di disporre delle autorizzazioni necessarie per completare questa guida.

  7. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  8. Abilita le API GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring e Cloud Trace:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli. 

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

  9. Installa Google Cloud CLI.

  10. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  11. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  12. Crea o seleziona un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Creare un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  13. Verifica di disporre delle autorizzazioni necessarie per completare questa guida.

  14. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  15. Abilita le API GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring e Cloud Trace:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli. 

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

Requisiti

Per utilizzare OpenTelemetry gestito per GKE, devi soddisfare i seguenti requisiti:

  • Il cluster deve avere GKE versione 1.34.1-gke.2178000 o successive.
  • gcloud CLI abilitata con la versione 551.0.0 o successive.
  • Se utilizzi Terraform per eseguire il provisioning dell'infrastruttura GKE, devi utilizzare il provider terraform-provider-google-beta alla versione v7.17.0 o successive.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per abilitare e utilizzare OpenTelemetry gestito da GKE, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Costi

Consulta la sezione Fatturazione per informazioni dettagliate sui costi connessi all'utilizzo di OpenTelemetry gestito per GKE.

Abilita OpenTelemetry gestito per GKE in un cluster

Per configurare Managed OpenTelemetry per GKE, devi procedere nel seguente modo:

  • Abilita OpenTelemetry gestito per GKE in un cluster.
  • Configura l'applicazione che stai monitorando per inviare indicatori all'endpoint dell'agente di raccolta gestito.

Quando abiliti OpenTelemetry gestito per GKE, nel cluster vengono implementati i seguenti oggetti:

  • Un deployment dell'agente di raccolta GKE Managed OpenTelemetry che viene eseguito il deployment all'interno dello spazio dei nomi gke-managed-otel. L'endpoint HTTP del raccoglitore OpenTelemetry gestito nel cluster per log, metriche e tracce è il seguente: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

  • Una definizione di risorsa personalizzata, instrumentations.telemetry.googleapis.com, che puoi utilizzare per configurare automaticamente i tuoi workload.

    Per ulteriori dettagli sulle risorse personalizzate, consulta la sezione Risorsa personalizzata nella documentazione di Kubernetes.

Abilitare su un nuovo cluster

Per abilitare OpenTelemetry gestito per GKE su un nuovo cluster, segui questi passaggi:

gcloud

Per un cluster Autopilot, utilizza il seguente comando:

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

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione o la zona.
  • VERSION: la versione, che deve essere 1.34.1-gke.2178000 o successiva.

Per un cluster Standard, utilizza il seguente comando:

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

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione o la zona.
  • VERSION: la versione, che deve essere 1.34.1-gke.2178000 o successiva.

Console

  • Per un cluster Autopilot, procedi nel seguente modo:

    1. Nella console Google Cloud , vai alla pagina Crea un cluster Autopilot.

      Vai a Crea un cluster Autopilot

    2. Nel pannello di navigazione, fai clic su Impostazioni avanzate.

    3. Nella sezione Operazioni, seleziona Abilita OpenTelemetry gestito.

    4. Fai clic su Salva.

  • Per un cluster Standard:

    1. Nella console Google Cloud , vai alla pagina Crea un cluster Kubernetes.

      Vai a Crea un cluster Kubernetes

    2. Nel pannello di navigazione, fai clic su Funzionalità.

    3. Nella sezione Operazioni, seleziona Abilita OpenTelemetry gestito.

    4. Fai clic su Salva.

Terraform

Per abilitare OpenTelemetry gestito per GKE su un nuovo cluster utilizzando Terraform, consulta l'esempio seguente:

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

Per scoprire di più sull'utilizzo di Terraform, consulta Supporto di Terraform per GKE.

Abilitare su un cluster esistente

Per abilitare Managed OpenTelemetry per GKE su un cluster esistente:

gcloud

  1. Assicurati che la versione del cluster sia 1.34.1-gke.2178000 o successiva. Per informazioni dettagliate su come eseguire l'upgrade di un cluster esistente, consulta Upgrade dei cluster Standard e Upgrade dei cluster Autopilot.

  2. Abilita OpenTelemetry gestito per GKE utilizzando il seguente comando:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster.
    • PROJECT_ID: l'ID progetto Google Cloud .
    • LOCATION: la regione o la zona.

Console

  1. Assicurati che la versione del cluster sia 1.34.1-gke.2178000 o successiva. Per informazioni dettagliate su come eseguire l'upgrade di un cluster esistente, consulta Upgrade dei cluster Standard e Upgrade dei cluster Autopilot.

  2. Nella console Google Cloud , vai alla pagina dei cluster Kubernetes:

    Vai ai cluster Kubernetes

  3. Fai clic sul nome del cluster.

  4. Nell'elenco Funzionalità, individua l'opzione Managed OpenTelemetry. Se è elencato come disattivato, fai clic su Modifica Modifica e poi seleziona Attiva OpenTelemetry gestito.

  5. Fai clic su Salva modifiche.

Terraform

Per abilitare Managed OpenTelemetry per GKE in un cluster esistente, aggiungi il blocco managed_opentelemetry_config alla risorsa google_container_cluster esistente, in modo simile all'esempio seguente:

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

Per scoprire di più sull'utilizzo di Terraform, consulta Supporto di Terraform per GKE.

Configura l'applicazione per utilizzare l'agente di raccolta OpenTelemetry gestito

Le applicazioni devono essere configurate per poter inviare indicatori all'endpoint dell'agente di raccolta gestito. Quando le applicazioni sono configurate, l'agente di raccolta Managed OpenTelemetry riceve i segnali dalle applicazioni in esecuzione sul cluster in cui è abilitato l'agente di raccolta. I segnali dell'applicazione includono tracce, metriche e log.

Per inviare segnali OpenTelemetry, le applicazioni devono essere già instrumentate per generare metriche OpenTelemetry. Per maggiori dettagli, vedi carichi di lavoro supportati.

Puoi configurare manualmente l'applicazione per inviare segnali all'endpoint dell'agente di raccolta gestito oppure puoi utilizzare la configurazione automatica. Non consigliamo di utilizzare entrambi i metodi insieme per lo stesso workload, perché la configurazione automatica può ignorare le modifiche manuali. Questa combinazione potrebbe rendere più difficile il monitoraggio delle modifiche alla configurazione.

Le sezioni seguenti descrivono come configurare le applicazioni per inviare indicatori al'agente di raccolta utilizzando la configurazione automatica.

Configurare la configurazione automatica

La configurazione automatica utilizza le variabili di ambiente per configurare i carichi di lavoro in modo da inviare segnali all'endpoint dell'agente di raccolta gestito.

Per abilitare l'inserimento automatico di variabili di ambiente nei pod, utilizza la risorsa personalizzata Instrumentation. Le variabili di ambiente hanno la configurazione OpenTelemetry e possono essere inserite in alcuni pod con etichette corrispondenti in uno spazio dei nomi o in tutti i pod di uno spazio dei nomi.

Poi, quando un'applicazione viene implementata nello spazio dei nomi, GKE utilizza la configurazione per inserire automaticamente le variabili di ambiente nei pod in cui vengono eseguiti i carichi di lavoro.

  1. Per configurare la risorsa personalizzata Instrumentation:

    1. Salva il seguente manifest Instrumentation in un file denominato 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

      Sostituisci quanto segue:

      • NAMESPACE: lo spazio dei nomi che contiene i pod di cui vuoi eseguire il targeting per la strumentazione automatica. Utilizza default per scegliere come target lo spazio dei nomi predefinito.
      • NAME: il nome del file manifest. In questo esempio, il nome è otlp-auto-config-namespace.yaml.
      • (Facoltativo) L'etichetta allegata ai pod da scegliere come target. Se viene specificato un selettore vuoto ({}), vengono presi di mira tutti i pod nello spazio dei nomi.
        • KEY: la chiave dell'etichetta.
        • VALUE: il valore dell'etichetta.
      • TRACE_RATIO: il rapporto tra i dati di traccia da raccogliere. Se non specificato, il valore predefinito è 1.0. Per ulteriori dettagli, vedi Modificare la frequenza di campionamento delle tracce.
      • METRICS_INTERVAL: l'intervallo, in millisecondi, dei dati di monitoraggio da raccogliere. Il valore predefinito è 30000. Il valore deve essere non negativo, con un minimo di 5000 ms, un massimo di 300.000 ms e un multiplo di 5000 ms. Per maggiori dettagli, consulta Modificare l'intervallo di esportazione delle metriche.

    2. Se vuoi modificare una delle impostazioni, consulta la sezione seguente per modificare la configurazione.

    3. Applica la configurazione eseguendo questo comando:

      kubectl apply -f otlp-auto-config-namespace.yaml

  2. Per inserire automaticamente le variabili di ambiente, devi eseguire il deployment dell'applicazione nello spazio dei nomi del cluster a cui è stata applicata la configurazione.

    • Per applicare la configurazione a un workload non ancora in esecuzione nello spazio dei nomi, esegui il deployment del workload utilizzando il seguente comando:

      kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE

      Sostituisci quanto segue:

      • DEPLOYMENT_NAME: il nome del deployment.
      • NAMESPACE: lo spazio dei nomi.

    • Per applicare la configurazione a un workload già in esecuzione nello spazio dei nomi, riesegui il deployment del workload utilizzando il seguente comando:

      kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

      Sostituisci quanto segue:

      • DEPLOYMENT_NAME: il nome del deployment.
      • NAMESPACE: lo spazio dei nomi.

Dopo aver applicato la configurazione al cluster, GKE configura automaticamente tutti i workload quando vengono sottoposti a deployment nel cluster. I carichi di lavoro vengono instrumentati inserendo variabili di ambiente nei pod in cui vengono eseguiti.

Quando un workload è configurato con queste variabili di ambiente è in esecuzione in un cluster in cui è stato eseguito il deployment del raccoglitore gestito, quando il workload viene eseguito invia segnali OpenTelemetry al raccoglitore gestito. Questi segnali sono disponibili per la visualizzazione in Google Cloud Observability.

Per maggiori dettagli sulla visualizzazione degli indicatori, vedi Visualizzare la telemetria. Per un esempio, consulta Genera dati di telemetria di esempio.

Modifica la configurazione

Per modificare la configurazione, devi:

  1. Modifica il file manifest Instrumentation.

  2. Applica la configurazione modificata.

  3. Esegui di nuovo il deployment o riavvia le applicazioni nello spazio dei nomi corrispondente del cluster dopo aver applicato la configurazione modificata.

Per ulteriori dettagli su questi passaggi, segui le istruzioni nella sezione Creare e implementare la configurazione.

Modificare la quantità o la frequenza della raccolta dei dati

Puoi modificare la quantità di dati di traccia raccolti modificando la frequenza di campionamento delle tracce.

Puoi modificare la frequenza con cui i dati di monitoraggio vengono inviati a Cloud Monitoring modificando l'intervallo di esportazione delle metriche.

Non puoi modificare la quantità o la frequenza dei dati di logging raccolti. Puoi, tuttavia, disattivare la raccolta di tutti i dati di logging, delle metriche o di tracciamento. Per maggiori dettagli, vedi Selezionare il tipo di indicatore da raccogliere.

Modificare la frequenza di campionamento delle tracce

Un carico di lavoro può generare una grande quantità di dati di traccia. Per la tua situazione, è importante determinare l'equilibrio tra il costo di raccolta e archiviazione dei dati e il livello di dettaglio necessario per renderli utili.

Il comportamento predefinito dell'SDK OpenTelemetry è always_on, che equivale a un rapporto di 1.

Di seguito è riportato un esempio di configurazione della frequenza di campionamento delle tracce. In questo esempio, il rapporto è 0,25, quindi i dati di traccia vengono raccolti a una velocità del 25%. Modifica questo numero di rapporto per cambiare la frequenza di campionamento.

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

Modificare l'intervallo di esportazione delle metriche

L'intervallo di esportazione delle metriche determina la granularità dei dati che puoi visualizzare nei grafici in Cloud Monitoring.

Di seguito è riportato un esempio di configurazione dell'intervallo di esportazione delle metriche. In questo esempio, l'intervallo di esportazione è 30.000 ms.

L'intervallo di esportazione delle metriche viene utilizzato per specificare l'intervallo di ritardo tra l'inizio di due esportazioni consecutive di metriche dall'SDK OpenTelemetry.

Il valore di questo intervallo deve essere non negativo, con un minimo di 5000 ms, un massimo di 300.000 ms e un multiplo di 5000 ms. Il valore è espresso in millisecondi.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Seleziona i tipi di indicatori da raccogliere

Puoi controllare quali tipi di indicatori vengono raccolti da un workload disattivando i tipi di indicatori che non vuoi raccogliere. I tipi di indicatori sono tracce, metriche e log.

Disattiva i tipi di indicatori utilizzando le variabili di ambiente nel container in cui viene eseguito il workload. Modifica le variabili di ambiente modificando la risorsa personalizzata Instrumentation e poi esegui nuovamente il deployment del workload nel container.

Il seguente esempio è un file manifest Instrumentation configurato per la raccolta solo dei dati di traccia. La raccolta di log e metriche è disabilitata perché meter_provider e logger_provider sono impostati su null.

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

Raccogliere dati su prompt e risposte multimodali

Puoi configurare Managed OpenTelemetry per GKE per raccogliere dati su prompt e risposte multimodali.

Questa funzionalità è disponibile per gli agenti LangGraph ReAct e per gli agenti di AI generativa creati con il framework Agent Development Kit (ADK).

Per configurare Managed OpenTelemetry per GKE in modo da raccogliere dati su prompt e risposte multimodali, procedi nel seguente modo:

  1. Configura il tuo Google Cloud progetto e l'SDK che utilizzi seguendo le istruzioni riportate nella sezione Raccogliere prompt e risposte multimodali.

  2. Crea o identifica un bucket Cloud Storage da utilizzare per raccogliere prompt e risposte multimodali. Per maggiori dettagli, consulta Creare un bucket.

  3. Concedi al account di servizio utilizzato dalla tua applicazione l'autorizzazione storage.objects.create per il bucket Cloud Storage.

    Questa autorizzazione consente all'applicazione di scrivere oggetti nel bucket Cloud Storage. Questi oggetti memorizzano i prompt e le risposte che l'applicazione agentic crea e riceve. Per saperne di più, consulta Impostare e gestire le policy IAM sui bucket.

  4. Configura il campo promptsResponses.uploadBasePath nella risorsa personalizzata Instrumentation, ad esempio:

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

    Sostituisci BUCKET_NAME con il nome del bucket Cloud Storage.

Quando la risorsa personalizzata Instrumentation viene aggiornata e i carichi di lavoro vengono riavviati, le variabili di ambiente che configurano i prompt e le risposte vengono inserite nei container dei carichi di lavoro.

Per maggiori dettagli sui tipi di contenuti multimediali che puoi raccogliere e su come esplorare i prompt e le risposte multimodali, consulta Raccogliere e visualizzare prompt e risposte multimodali.

Disattivare la configurazione automatica dei workload

Per disattivare la strumentazione automatica dei workload con la configurazione specificata, elimina la risorsa personalizzata Instrumentation dal cluster. Per farlo, utilizza il comando seguente:

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

Sostituisci quanto segue:

  • INSTRUMENTATION_NAME: il nome della risorsa personalizzata Instrumentation.
  • NAMESPACE: lo spazio dei nomi che contiene i pod in cui vuoi disattivare la configurazione automatica.

Per disattivare temporaneamente l'inserimento automatico variabile di ambiente mantenendo la configurazione della strumentazione automatica per un utilizzo futuro, imposta autoInstrumentationConfig.configInjection.enabled su false e applica la risorsa personalizzata aggiornata.

Di seguito è riportato un esempio della risorsa personalizzata con l'inserimento automatico della variabile di ambiente disattivato temporaneamente:

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

Dopo aver eliminato la risorsa personalizzata o averla aggiornata per disattivare l'inserimento automatico della configurazione, GKE non strumenta automaticamente i nuovi carichi di lavoro di cui è target la risorsa personalizzata Instrumentation.

Per interrompere l'esportazione di segnali OTLP nel collettore gestito da un carico di lavoro precedentemente instrumentato dalla risorsa personalizzata, devi riavviare il carico di lavoro affinché la modifica venga applicata. Per farlo, utilizza il comando seguente:

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

Sostituisci quanto segue:

  • DEPLOYMENT_NAME: il nome del deployment.
  • NAMESPACE: lo spazio dei nomi.

Visualizzare la telemetria

Quando un workload configurato viene eseguito su GKE in cui è abilitato Managed OpenTelemetry per GKE, i segnali OpenTelemetry vengono inviati a Google Cloud Observability.

Per informazioni dettagliate sulla visualizzazione dei dati in Google Cloud Observability, consulta quanto segue:

Genera dati di telemetria di esempio

Questa sezione descrive il deployment di un'applicazione di esempio e il reindirizzamento dell'applicazione all'endpoint OTLP del raccoglitore Managed OpenTelemetry. Puoi quindi visualizzare la telemetria in Google Cloud.

L'applicazione di esempio è un piccolo generatore che esporta tracce, log e metriche all'endpoint HTTP dell'agente di raccolta OpenTelemetry gestito nel cluster. L'endpoint OTLP è hardcoded all'interno dell'applicazione e punta a http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

Se hai già instrumentato un'applicazione con un SDK OpenTelemetry, puoi generare dati di telemetria dalla tua applicazione indirizzandola all'endpoint del collettore o configurando la strumentazione automatica per l'applicazione.

Per eseguire il deployment dell'applicazione di esempio:

  1. Connettiti al cluster in cui hai abilitato OpenTelemetry gestito. Per farlo, consulta Impostare un cluster predefinito per i comandi kubectl.

  2. Esegui questo comando:

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

    Dopo alcuni minuti, la telemetria generata dall'applicazione inizia a fluire tramite l'agente di raccolta al backend Google Cloud per ogni segnale.

    1. Verifica che la telemetria venga inserita visualizzando log, metriche e tracce dell'applicazione demo nella console Google Cloud :

    2. Per visualizzare le metriche:

      1. Nella console Google Cloud , vai alla pagina Metrics Explorer:

        Vai a Esplora metriche

      2. Esegui la seguente query PromQL in Metrics Explorer:

        sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))

    3. Per visualizzare le tracce:

      1. Nella console Google Cloud , vai alla pagina Esplora tracce.

        Vai a Esplora tracce

      2. Filtra gli span di traccia in base al nome dello span uguale a lets-go.

    4. Per visualizzare i log:

      1. Nella console Google Cloud , vai alla pagina Esplora log.

        Vai a Esplora log

      2. Esegui questa query:

        resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"

Disabilita OpenTelemetry gestito per GKE

Puoi disabilitare Managed OpenTelemetry per GKE nel cluster. Quando disattivi il raccoglitore, Managed OpenTelemetry collector viene rimosso dal cluster e non vengono raccolti nuovi dati di telemetria.

Per disattivare Managed OpenTelemetry per GKE, segui questi passaggi.

gcloud

Per disabilitare Managed OpenTelemetry per GKE per un cluster, esegui il seguente comando gcloud:

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

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione o la zona.

Console

  1. Nella console, vai all'elenco dei cluster:

    Vai ai cluster Kubernetes

  2. Seleziona il cluster in cui vuoi disattivare il raccoglitore Managed OpenTelemetry.

  3. In Dettagli cluster, accanto a OpenTelemetry gestito, seleziona l'icona di modifica.

  4. Deseleziona la casella di controllo per disattivare la funzionalità.

Terraform

Per disattivare OpenTelemetry gestito per GKE, aggiorna il blocco managed_opentelemetry_config nella risorsa google_container_cluster per impostare l'ambito su NONE.

  1. Aggiorna il file di configurazione Terraform:

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

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

  2. Applica la configurazione Terraform:

    terraform apply

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster.
  • LOCATION: la regione o la zona.
  • PROJECT_ID: l'ID progetto Google Cloud .

Quando disattivi Managed OpenTelemetry per GKE, la definizione di risorsa personalizzata Instrumentation e le risorse personalizzate Instrumentation non vengono rimosse dal cluster. Se riattivi OpenTelemetry gestito, questo utilizza la configurazione conservata nelle risorse personalizzate Instrumentation.

Se hai dati di telemetria già raccolti da Managed OpenTelemetry per GKE, la disattivazione dell'agente di raccolta non influisce su questi dati. I dati esistenti vengono comunque archiviati in Google Cloud Observability e non vengono raccolti nuovi dati di telemetria.

Risoluzione dei problemi

Workload privilegiati dei partner Autopilot

Se provi a utilizzare la configurazione automatica con un carico di lavoro privilegiato del partner Autopilot, potresti notare che il pod del carico di lavoro è stato rifiutato.

L'inserimento della configurazione OpenTelemetry non è supportato per i carichi di lavoro con privilegi dei partner GKE Autopilot. Il targeting di questi carichi di lavoro utilizzando una risorsa personalizzata Instrumentation per abilitare l'inserimento della variabile di ambiente OpenTelemetry potrebbe causare la mancata corrispondenza del carico di lavoro con la lista consentita dei carichi di lavoro privilegiati di Autopilot, il che significa che il pod con configurazione inserita verrebbe rifiutato da GKE Autopilot.

Log, metriche o tracce non sono visibili nella console Google Cloud

I dati potrebbero non essere visibili per diversi motivi. Questi motivi includono autorizzazioni mancanti per visualizzare i dati o una configurazione errata che impedisce la raccolta dei dati.

Ecco alcuni passaggi che puoi seguire per risolvere i problemi più comuni:

  • Assicurati di aver attivato tutte le API richieste nel tuo progetto.

  • Assicurati che la risorsa personalizzata Instrumentation sia configurata correttamente, con lo spazio dei nomi corrispondente a quello in cui viene eseguito il carico di lavoro e il selettore corrispondente all'etichetta del carico di lavoro.

  • Ispeziona il pod del workload per verificare che le variabili di ambiente vengano inserite correttamente.

  • Controlla i log dei container dell'agente di raccolta OpenTelemetry per verificare se sono presenti errori nell'agente di raccolta. Per farlo, esegui questo comando:

    kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector

La disattivazione di un segnale di telemetria non funziona

Quando disattivi un segnale di telemetria utilizzando la risorsa personalizzata Instrumentation, assicurati di applicare la risorsa personalizzata e di eseguire nuovamente il deployment dei carichi di lavoro.

Quando applichi la risorsa personalizzata, utilizza Server-Side Apply nel comando kubectl apply quando aggiorni la risorsa personalizzata Instrumentation.

Per informazioni dettagliate sulla disattivazione di un indicatore di telemetria, vedi Selezionare i tipi di indicatori da raccogliere.

Le variabili inserite da OpenTelemetry non sono visibili nel mio workload

Le variabili vengono inserite nei container dei pod del workload , non nel workload. Controlla i pod, non gli oggetti proprietari come ReplicaSet o Deployment.

Ad esempio, per verificare che le variabili vengano inserite correttamente per il carico di lavoro di esempio nello spazio dei nomi predefinito utilizzato nella sezione precedente Genera dati di telemetria, procedi nel seguente modo:

  1. Esegui questo comando:

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

  2. Esamina il spec.containers[*].env dei pod.

  3. Assicurati che esista un oggetto Instrumentation nello stesso spazio dei nomi e verifica che sia destinato al pod e che la funzionalità di inserimento della configurazione sia attivata. Per farlo, esegui questo comando:

    kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml

Le variabili vengono inserite nei container solo quando vengono creati i pod perché l'API Kubernetes non consente di modificare la maggior parte dei campi nella specifica di un pod esistente, ad esempio le variabili di ambiente. Affinché la configurazione abbia effetto sui workload creati prima della creazione dell'oggetto Instrumentation, riavvia il workload. Ad esempio, per un deployment denominato telemetry-gen-app, esegui questo comando:

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

Una quantità eccessiva di dati di traccia in Cloud Trace

Per ridurre i dati raccolti da Cloud Trace, puoi configurare un campionatore basato sul parent con un rapporto ID traccia per campionare solo una percentuale delle tue tracce.

Ad esempio, aggiungi quanto segue all'oggetto Instrumentation:

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

Il comportamento predefinito dell'SDK OpenTelemetry è la tracciabilità "always_on", che equivale a un rapporto di 1.

Le variabili di ambiente non corrispondono alla configurazione

Se hai apportato un aggiornamento all'oggetto Instrumentation, verifica di aver riavviato i pod come descritto nella sezione Modificare la configurazione.

Se visualizzi la configurazione errata per il pod, verifica che il pod sia correttamente preso di mira dall'oggetto Instrumentation e che non siano presenti più oggetti Instrumentation che hanno come target lo stesso pod:

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

Tieni presente che un selettore vuoto ha come target tutti i pod nel relativo spazio dei nomi.

Se più strumentazioni hanno come target lo stesso pod al momento della creazione, viene applicata quella aggiornata per ultima.

Il comando kubectl logs non restituisce alcun output

Quando i log vengono trasmessi in streaming direttamente da un'applicazione a un collector OpenTelemetry, i log ignorano il percorso di logging standard per il runtime del container. Questo è lo scenario comune quando si utilizza OpenTelemetry per i log. Per impostazione predefinita, l'esportatore invia i log all'endpoint otlp anziché ai flussi stdout e stderr.

In questo caso, poiché i log non vengono scritti nei flussi stdout o stderr per l'acquisizione da parte del runtime del container, il comando kubectl logs non mostrerà alcun output per l'applicazione. L'output di logging è disponibile in Cloud Logging.

Se vuoi utilizzare l'SDK OpenTelemetry e inviare anche i log al flusso stdout, puoi configurarlo utilizzando l'esportatore di log. Per saperne di più, consulta Esportatore di log - Output standard.

Passaggi successivi