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 dalle applicazioni in esecuzione su GKE.

Per maggiori dettagli sul funzionamento di OpenTelemetry gestito per GKE, consulta OpenTelemetry gestito per GKE.

Puoi utilizzare OpenTelemetry gestito per GKE per:

  • Configura i workload in esecuzione su GKE per inviare tracce, metriche e log OpenTelemetry Protocol (OTLP) al raccoglitore gestito.
  • Ricevere tracce, metriche e log OpenTelemetry Protocol (OTLP) dalle applicazioni in esecuzione su GKE.
  • Esportare i dati in Google Cloud Observability.

Se hai bisogno di filtri e controlli a livello di Collector, utilizza il Collector OpenTelemetry creato da Google 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 progetto Google Cloud .

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

    • Crea 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, se non sono già abilitate:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). 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 progetto Google Cloud .

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

    • Crea 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, se non sono già abilitate:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). 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 successiva. Per configurare il protocollo di esportazione OTLP come gRPC nella risorsa personalizzata Instrumentation, devi utilizzare GKE 1.37.1-gke.1697000 o versioni successive.
  • gcloud CLI abilitata con la versione 576.0.0 o successiva.
  • Se utilizzi Terraform per eseguire il provisioning dell'infrastruttura GKE, devi utilizzare terraform-provider-google nella versione v8.8.0 o successiva.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per abilitare e utilizzare OpenTelemetry gestito da GKE, chiedi all'amministratore di concederti i seguenti ruoli IAM nel 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

Per informazioni dettagliate sui costi relativi all'utilizzo di OpenTelemetry gestito per GKE, consulta Fatturazione.

Abilita OpenTelemetry gestito per GKE in un cluster

Per configurare OpenTelemetry gestito per GKE, devi:

  • Abilita OpenTelemetry gestito per GKE in un cluster.
  • Configura l'applicazione che stai monitorando per inviare indicatori all'endpoint del raccoglitore gestito.

Quando abiliti OpenTelemetry gestito per GKE, i seguenti oggetti vengono sottoposti a deployment nel cluster:

  • Un deployment del Collector OpenTelemetry gestito da GKE di cui viene eseguito il deployment nello spazio dei nomi gke-managed-otel. Gli endpoint del raccoglitore OpenTelemetry gestito nel cluster per log, metriche e tracce sono i seguenti:
    • Endpoint HTTP: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318
    • Endpoint gRPC: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317

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

    Per maggiori dettagli sulle risorse personalizzate, consulta Risorsa personalizzata nella documentazione di Kubernetes.

Abilita 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 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 di GKE. Consulta i requisiti per la versione minima che puoi utilizzare.

Per un cluster Standard, utilizza il seguente comando:

gcloud 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 di GKE. Consulta i requisiti per la versione minima che puoi utilizzare.

Console

  • Per un cluster Autopilot, segui questi passaggi:

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

      Vai a Crea un cluster Autopilot

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

    3. Nella sezione Operazioni, seleziona Abilita OpenTelemetry gestito.

    4. Fai clic su Crea.

  • Per un cluster Standard, segui questi passaggi:

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

      Vai a Crea un cluster Kubernetes

    2. Nel riquadro di navigazione, fai clic su Impostazioni avanzate.
    3. Nella riga OpenTelemetry gestito, fai clic su Modifica configurazione.
    4. Seleziona Abilita OpenTelemetry gestito.
    5. Fai clic su Salva.
    6. Fai clic su Crea.

Terraform

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

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  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.

Abilita su un cluster esistente

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

gcloud

  1. Assicurati che la versione del cluster soddisfi i requisiti. Per maggiori dettagli 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 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 soddisfi i requisiti. Per maggiori dettagli 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 OpenTelemetry gestito. Se è elencato come disattivato, fai clic su Modifica e poi seleziona Abilita OpenTelemetry gestito.

  5. Fai clic su Salva modifiche.

Terraform

Per abilitare Managed OpenTelemetry per GKE su 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 = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  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 il raccoglitore OpenTelemetry gestito

Le applicazioni devono essere configurate per poter inviare indicatori all'endpoint del raccoglitore gestito. Una volta configurate le applicazioni, il raccoglitore OpenTelemetry gestito riceve gli indicatori dalle applicazioni in esecuzione sul cluster in cui è abilitato il raccoglitore. I segnali dell'applicazione includono tracce, metriche e log.

Per inviare indicatori OpenTelemetry, le applicazioni devono essere già instrumentate per generare metriche OpenTelemetry. Per maggiori dettagli, consulta Workload supportati.

Puoi configurare manualmente l'applicazione per inviare indicatori all'endpoint del raccoglitore gestito oppure puoi utilizzare la configurazione automatica. Ti sconsigliamo di utilizzare entrambi i metodi insieme per lo stesso workload, perché la configurazione automatica può eseguire l'override delle modifiche manuali. Questa combinazione potrebbe rendere più difficile monitorare le modifiche alla configurazione.

Le sezioni seguenti descrivono come configurare le applicazioni per l'invio di indicatori al raccoglitore utilizzando la configurazione automatica.

Configura la configurazione automatica

La configurazione automatica utilizza le variabili di ambiente per configurare i workload in modo che inviino indicatori all'endpoint del raccoglitore gestito.

Per abilitare l'inserimento automatico delle 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.

In seguito, quando un'applicazione viene sottoposta a deployment nello spazio dei nomi, GKE utilizza la configurazione per inserire automaticamente le variabili di ambiente nei pod in cui vengono eseguiti i workload.

  1. Per configurare la risorsa personalizzata Instrumentation, segui questi passaggi:

    1. Salva il seguente manifest di strumentazione 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 che vuoi scegliere come target per la strumentazione automatica. Utilizza default per scegliere come target lo spazio dei nomi predefinito.
      • NAME: il nome dell'oggetto Instrumentation nel file manifest.
      • (Facoltativo) L'etichetta associata ai pod da scegliere come target. Se viene specificato un selettore vuoto ({}), vengono scelti come target tutti i pod nello spazio dei nomi.
        • KEY: la chiave dell'etichetta.
        • VALUE: il valore dell'etichetta.
      • TRACE_RATIO: il rapporto dei dati di traccia da raccogliere. Se non specificato, il valore predefinito è 1.0. Per maggiori dettagli, consulta Modifica 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 Modifica 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 è 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, rifai 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 viene eseguito il deployment nel cluster. I workload vengono strumentati 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, durante l'esecuzione del workload invia indicatori OpenTelemetry al raccoglitore gestito. Questi indicatori sono disponibili per la visualizzazione in Google Cloud Observability.

Per maggiori dettagli sulla visualizzazione degli indicatori, consulta Visualizza 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 di strumentazione.

  2. Applica la configurazione modificata.

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

Per maggiori dettagli su questi passaggi, segui le istruzioni riportate nella sezione Configura la configurazione automatica.

Configura il protocollo di esportazione OTLP (HTTP o gRPC)

Per impostazione predefinita, la configurazione automatica configura i workload per l'esportazione della telemetria su HTTP. In GKE 1.37.1-gke.1697000 e versioni successive, puoi configurare la risorsa personalizzata Instrumentation per esportare la telemetria tramite HTTP o gRPC.

Una risorsa personalizzata di strumentazione supporta un solo protocollo per tutti i provider. Per utilizzare gRPC, imposta l'esportatore su otlp_grpc: {} per ogni provider che utilizzi e imposta i provider inutilizzati su null. Ad esempio, per disattivare le metriche, utilizza meter_provider: null.

L'esempio seguente è un file manifest di strumentazione configurato per esportare la telemetria su gRPC per i provider di tracce, metriche e logging:

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"
      processors:
      - batch:
          exporter:
            otlp_grpc: {}
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
          exporter:
            otlp_grpc: {}
    logger_provider:
      processors:
      - batch:
          exporter:
            otlp_grpc: {}

Sostituisci quanto segue:

  • NAMESPACE: lo spazio dei nomi che contiene i pod che vuoi scegliere come target per la strumentazione automatica. Utilizza default per scegliere come target lo spazio dei nomi predefinito.
  • NAME: il nome dell'oggetto Instrumentation nel file manifest.
  • (Facoltativo) L'etichetta associata ai pod da scegliere come target. Se viene specificato un selettore vuoto ({}), vengono scelti come target tutti i pod nello spazio dei nomi.
    • KEY: la chiave dell'etichetta.
    • VALUE: il valore dell'etichetta.
  • TRACE_RATIO: il rapporto dei dati di traccia da raccogliere. Se non specificato, il valore predefinito è 1.0. Per maggiori dettagli, consulta Modifica 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 Modifica l'intervallo di esportazione delle metriche.

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 della raccolta dei dati di logging. Tuttavia, puoi disattivare la raccolta di tutti i dati di logging, metriche o tracciamento. Per maggiori dettagli, consulta Seleziona il tipo di indicatore da raccogliere.

Modifica la frequenza di campionamento delle tracce

Un workload 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 affinché i dati siano 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 con una frequenza del 25%. Modifica questo numero per cambiare la frequenza di campionamento.

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

Modifica 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 è di 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 quelli che non vuoi raccogliere. I tipi di indicatori sono tracce, metriche e log.

Puoi disattivare i tipi di indicatori utilizzando le variabili di ambiente nel container in cui viene eseguito il workload. Puoi modificare le variabili di ambiente modificando la risorsa personalizzata Instrumentation e quindi eseguendo nuovamente il deployment del workload nel container.

L'esempio seguente è un file manifest di strumentazione configurato per la raccolta di soli 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 i dati di prompt e risposte multimodali

Nel cluster GKE versione 1.35.2-gke.1210000 o successive, puoi configurare Managed OpenTelemetry per GKE in modo da raccogliere dati di prompt e risposte multimodali.

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

Quando raccogli dati di prompt e risposte multimodali con Managed OpenTelemetry per GKE, vengono raccolti i contenuti completi dei prompt e delle risposte dell'utente finale. I dati dei prompt e delle risposte vengono archiviati in un bucket Cloud Storage. Per informazioni dettagliate su come gestire il bucket di archiviazione, incluso il controllo dell'accesso o l'eliminazione dei dati, consulta la documentazione di Cloud Storage.

Puoi utilizzare prodotti come Model Armor e Sensitive Data Protection per gestire i dati sensibili che potrebbero essere presenti nei prompt e nelle risposte.

Per configurare Managed OpenTelemetry per GKE in modo che raccolga i dati dei prompt e delle risposte multimodali, segui questi passaggi:

  1. Configura il tuo progetto Google Cloud e l'SDK che stai utilizzando seguendo le istruzioni nella sezione Raccogli prompt e risposte multimodali.

  2. Crea o identifica un bucket Cloud Storage da utilizzare per raccogliere prompt e risposte multimodali. Per maggiori dettagli, consulta Crea 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 alla tua applicazione di scrivere oggetti nel bucket Cloud Storage. Questi archivi di oggetti memorizzano i prompt e le risposte che l'applicazione agentica crea e riceve. Per saperne di più, consulta Imposta e gestisci 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 workload vengono riavviati, le variabili di ambiente che configurano i prompt e le risposte vengono inserite nei container dei workload.

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

Disabilita 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 seguente comando:

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 per i quali vuoi disattivare la configurazione automatica.

Per disattivare temporaneamente l'inserimento automatico variabile di ambiente, preservando al contempo 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 delle variabile di ambiente temporaneamente disabilitato:

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 disabilitare l'inserimento automatico della configurazione, GKE non strumenta automaticamente i nuovi workload che sono il target della risorsa personalizzata Instrumentation.

Per interrompere l'esportazione degli indicatori OTLP al raccoglitore gestito da un workload precedentemente strumentato dalla risorsa personalizzata, devi riavviare il workload affinché la modifica venga applicata. Per farlo, utilizza 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.

Visualizza la telemetria

Quando un workload configurato viene eseguito su GKE con OpenTelemetry gestito per GKE abilitato, 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 suo indirizzamento all'endpoint OTLP del raccoglitore OpenTelemetry gestito. Puoi quindi visualizzare la telemetria in Google Cloud.

L'applicazione di esempio è un piccolo generatore che esporta tracce, log e metriche nel raccoglitore OpenTelemetry gestito nel cluster. L'applicazione è hardcoded per utilizzare l'endpoint gRPC del collector: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317

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

Per eseguire il deployment dell'applicazione di esempio, segui questi passaggi:

  1. Connettiti al cluster in cui hai abilitato OpenTelemetry gestito. Per farlo, consulta Imposta 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 attraverso l'agente di raccolta al backend Google Cloud per ogni indicatore.

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

    2. Per visualizzare le metriche, segui questi passaggi:

      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, segui questi passaggi:

      1. Nella console Google Cloud , vai alla pagina Trace Explorer.

        Vai a Trace Explorer

      2. Filtra gli intervalli di traccia in base al nome dell'intervallo 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 OpenTelemetry gestito per GKE nel cluster. Quando disattivi il raccoglitore, il raccoglitore OpenTelemetry gestito 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 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 OpenTelemetry gestito.

  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" {
  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 disabiliti Managed OpenTelemetry per GKE, la CustomResourceDefinition di strumentazione e tutte le risorse personalizzate di strumentazione che hai creato non vengono rimosse dal cluster.

Se riattivi OpenTelemetry gestito, viene utilizzata la configurazione conservata nelle risorse personalizzate di strumentazione.

Se hai dati di telemetria già raccolti da OpenTelemetry gestito per GKE, la disattivazione del raccoglitore 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 con privilegi dei partner Autopilot

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

L'inserimento della configurazione OpenTelemetry non è supportato per i workload con privilegi dei partner GKE Autopilot. Se scegli come target questi workload utilizzando una risorsa personalizzata di strumentazione per abilitare l'inserimento di variabile di ambiente OpenTelemetry, il workload potrebbe non corrispondere alla lista consentita dei workload con privilegi di Autopilot, il che significa che il pod con configurazione inserita verrebbe rifiutato da GKE Autopilot.

I log, le metriche o le 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 i passaggi che puoi seguire per risolvere i problemi comuni:

  • Assicurati di aver abilitato 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 è in esecuzione il workload e il selettore corrispondente all'etichetta del workload.

  • Ispeziona il pod del workload per verificare se le variabili di ambiente sono inserite correttamente.

  • Controlla i log del container del raccoglitore OpenTelemetry per verificare se sono presenti errori nel raccoglitore. Per farlo, esegui questo comando:

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

La disattivazione di un indicatore di telemetria non funziona

Quando disattivi un indicatore di telemetria utilizzando la risorsa personalizzata Instrumentation, assicurati di applicare la risorsa personalizzata e di rifare il deployment dei workload.

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

Per maggiori dettagli sulla disattivazione di un indicatore di telemetria, consulta Seleziona 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 workload di esempio nello spazio dei nomi predefinito utilizzato nella sezione precedente Genera dati di telemetria, segui questi passaggi:

  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 abbia come target il pod e che la funzionalità di inserimento della configurazione sia abilitata. 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 il seguente comando:

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

Una quantità eccessiva di dati di traccia in Cloud Trace

Per ridurre la raccolta dei dati da parte di Cloud Trace, puoi configurare un campionatore basato sul livello principale con un rapporto ID traccia per campionare solo una percentuale delle 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 è il tracciamento "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 Modifica la configurazione.

Se la configurazione del pod non è corretta, verifica che il pod sia scelto correttamente come target 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 suo spazio dei nomi.

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

Il comando kubectl logs non restituisce alcun output

Quando i log vengono trasmessi direttamente da un'applicazione a un raccoglitore OpenTelemetry, bypassano 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é agli stream stdout e stderr.

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

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

Passaggi successivi