OpenTelemetry gestito per GKE

Questo documento descrive OpenTelemetry gestito per Google Kubernetes Engine (GKE), che ti consente di inviare tracce, metriche e log OpenTelemetry Protocol (OTLP) a Google Cloud Observability dalle applicazioni in esecuzione su GKE. OpenTelemetry gestito fornisce l'unica soluzione gestita da Google Cloud per la raccolta dei dati di traccia su GKE.

Per utilizzare OpenTelemetry gestito per Google Kubernetes Engine (GKE), le applicazioni devono essere già strumentate per generare indicatori utilizzando il protocollo OpenTelemetry. Per maggiori dettagli, consulta Workload supportati.

OpenTelemetry gestito per GKE ha due componenti:

  • Raccolta gestita: il raccoglitore gestito fornisce un endpoint OpenTelemetry Protocol all'interno del cluster come destinazione per i workload per l'invio di tracce, metriche e log in formato OTLP, senza dover gestire un raccoglitore.

  • Configurazione automatica: una risorsa personalizzata chiamata Instrumentation consente una configurazione automatica per i workload GKE per generare e importare tracce, metriche e log OpenTelemetry correlati. Questo approccio supporta l'Agent Development Kit (ADK) e i dati di prompt e risposte multimodali.

    Puoi utilizzare la risorsa personalizzata Instrumentation per i workload che utilizzano l'SDK OpenTelemetry e sono configurati con variabili di ambiente OpenTelemetry standard. Questa risorsa personalizzata di strumentazione, instrumentations.telemetry.googleapis.com, è una risorsa diversa dalla risorsa di strumentazione per l'operatore OpenTelemetry.

Per i passaggi per utilizzare OpenTelemetry gestito per GKE, consulta Esegui il deployment di OpenTelemetry gestito per GKE.

OpenTelemetry gestito per GKE ti consente di raccogliere la telemetria OTLP senza dover gestire e utilizzare un raccoglitore OpenTelemetry. L'esecuzione di un tuo raccoglitore può comportare un overhead, tra cui autenticazione, configurazione, upgrade e monitoraggio. Tuttavia, se hai bisogno di filtri e controlli a livello di Collector, puoi utilizzare il Collector OpenTelemetry creato da Google anziché questo servizio gestito.

OpenTelemetry fornisce API, librerie e SDK per generare tracce, metriche e log distribuiti per il monitoraggio delle applicazioni. Per saperne di più su OpenTelemetry, consulta la documentazione su OpenTelemetry e sul protocollo OpenTelemetry (OTLP). Per maggiori dettagli sulla generazione e sulla raccolta dei dati comportamentali di runtime dell'applicazione, consulta Osservabilità per gli sviluppatori di applicazioni.

Come funziona OpenTelemetry gestito per GKE

OpenTelemetry gestito per GKE ha due componenti: raccolta gestita e configurazione automatica.

Raccolta gestita

La raccolta gestita fornisce un endpoint OTLP in-cluster eseguendo il deployment di un agente di raccolta OpenTelemetry gestito nel cluster. Questo endpoint OTLP all'interno del cluster riceve tracce, metriche e log in formato OTLP. Per ricevere i dati da un workload, quest'ultimo deve essere configurato per inviare i dati al raccoglitore.

L'endpoint a cui il workload invia i dati dipende dal protocollo che utilizzi, come segue:

  • L'URL http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318 per l'endpoint HTTP.
  • L'URL http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317 per l'endpoint gRPC.

La raccolta gestita invia i dati raccolti a Google Cloud Observability. I dati sono quindi disponibili nei seguenti servizi:

Il raccoglitore gestito può essere attivato per un cluster GKE utilizzando la console o gcloud CLI. Per le istruzioni, consulta Abilita OpenTelemetry gestito per GKE in un cluster.

Configurazione automatica

La configurazione automatica consente a GKE di configurare i workload in esecuzione su GKE per inviare indicatori all'endpoint del raccoglitore gestito.

Esistono diversi metodi che possono essere utilizzati per configurare un workload. La configurazione automatica utilizza le variabili di ambiente inserite nel container del workload per fare in modo che il workload invii indicatori al raccoglitore gestito. Se configuri manualmente il workload, puoi utilizzare altri metodi. Per i dettagli, consulta Configurazione manuale.

Quando utilizzi la configurazione automatica, definisci la configurazione utilizzando la risorsa personalizzata Instrumentation. Poi, GKE inserisce le variabili di ambiente, come l'endpoint dell'esportatore OTLP, nei container del workload. Quando i container del workload hanno queste variabili di ambiente, durante l'esecuzione del workload i dati OpenTelemetry vengono inviati al raccoglitore gestito.

La configurazione automatica è disponibile per i workload che supportano in modo nativo OpenTelemetry, ovvero che utilizzano l'SDK OpenTelemetry e sono configurati utilizzando variabili di ambiente OpenTelemetry standard. Per maggiori dettagli, consulta Workload supportati.

Per istruzioni su come configurare l'applicazione utilizzando la configurazione automatica, consulta Configura l'applicazione per l'utilizzo del raccoglitore OpenTelemetry gestito.

La risorsa personalizzata Instrumentation

Utilizza la risorsa personalizzata Instrumentation per:

  • Specifica se inserire le variabili di ambiente nei container dei pod selezionati o di tutti i pod in uno spazio dei nomi.
  • Controllare il tipo di dati raccolti (log, metriche e tracce).
  • Controlla la frequenza con cui i dati delle metriche vengono inviati al raccoglitore gestito.
  • Controlla la frequenza di campionamento dei dati di traccia.
  • Controlla il protocollo di trasporto OTLP (HTTP o gRPC) utilizzato per esportare la telemetria al raccoglitore gestito.

Per informazioni dettagliate su come utilizzare la risorsa personalizzata Instrumentation, consulta Modifica la configurazione.

Inserisci automaticamente le variabili di ambiente

Per inserire automaticamente le variabili di ambiente OpenTelemetry nei tuoi workload GKE, devi configurare un oggetto Instrumentation nel cluster. Poi, quando esegui il deployment dell'applicazione nel cluster con l'oggetto Instrumentation, le variabili vengono inserite da GKE.

L'oggetto Instrumentation deve trovarsi nel cluster quando viene eseguito il deployment dell'applicazione e vengono creati i pod. Se hai eseguito il deployment dell'applicazione prima di creare l'oggetto Instrumentation, devi riavviare i pod dell'applicazione per attivare l'inserimento automatico delle variabili di ambiente.

Variabili di ambiente

Quando viene eseguito il deployment di un workload nello spazio dei nomi in cui è abilitata la configurazione automatica, GKE inserisce le variabili di ambiente nei container dei workload. Queste variabili di ambiente sono variabili OpenTelemetry della configurazione dell'SDK OpenTelemetry.

L'elenco seguente contiene tutte le variabili di ambiente che possono essere inserite da OpenTelemetry gestito per GKE. Le variabili di ambiente specifiche inserite in un container dipendono dalla configurazione nella risorsa personalizzata Instrumentation.

Le variabili di ambiente che possono essere inserite automaticamente nei container sono le seguenti:

  • Endpoint e protocollo dell'esportatore OpenTelemetry.
    • OTEL_EXPORTER_OTLP_ENDPOINT: un URL dell'endpoint di base per qualsiasi tipo di indicatore. A seconda dell'esportatore configurato nella risorsa personalizzata Instrumentation, il valore di questa variabile di ambiente è l'endpoint HTTP del raccoglitore OpenTelemetry gestito nel cluster (http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318, predefinito) o l'endpoint gRPC (http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317).
    • OTEL_EXPORTER_OTLP_PROTOCOL: specifica il protocollo di trasporto OTLP utilizzato dall'esportatore dell'SDK. Il valore di questa variabile di ambiente è uno dei seguenti, a seconda del protocollo di trasporto OTLP che utilizzi:
      • grpc se utilizzi il protocollo di trasporto otlp_grpc.
      • http/protobuf se non specifichi un protocollo di trasporto o se utilizzi il protocollo di trasporto otlp_http.
  • Configurazione del rapporto di campionamento Trace.
    • OTEL_TRACES_SAMPLER: imposta il campionatore utilizzato per campionare le tracce dall'SDK su uno dei seguenti valori:
      • parentbased_traceidratio quando il campionamento delle tracce è configurato nella risorsa personalizzata.
      • parentbased_always_on è il valore predefinito di questa variabile di ambiente. Viene utilizzata se questa variabile di ambiente non è configurata o è null nella risorsa personalizzata.
    • OTEL_TRACES_SAMPLER_ARG: specifica il rapporto di campionamento delle tracce (tra 0,0 e 1,0). Se non è configurato nella risorsa personalizzata, viene utilizzato 1.0.
  • Intervallo di ritardo tra l'inizio di due esportazioni di metriche consecutive.
    • OTEL_METRIC_EXPORT_INTERVAL: l'intervallo di tempo (in millisecondi) tra l'inizio di due tentativi di esportazione (min: 5000, max: 300.000, predefinito: 30.000).
  • Disattivazione dell'esportazione della telemetria OTLP per tipo di indicatore. Gli esportatori di indicatori sono disattivati quando tracer_provider, meter_provider o logger_provider sono impostati su null nella risorsa personalizzata Instrumentation.
    • OTEL_TRACES_EXPORTER: disattiva l'esportazione delle tracce se impostato su none. Valore predefinito: otlp.
    • OTEL_METRICS_EXPORTER: disattiva l'esportazione delle metriche se impostato su none. Valore predefinito: otlp.
    • OTEL_LOGS_EXPORTER: disattiva l'esportazione dei log se impostato su none. Valore predefinito: otlp.
  • Identificazione dei pod hostNetwork per l'associazione dei metadati tramite il processore di attributi Kubernetes del raccoglitore OpenTelemetry.
    • K8S_POD_UID: l'UID del pod di un pod hostNetwork per la compilazione dell'impostazione k8s.pod.uid nella variabile di ambiente OTEL_RESOURCE_ATTRIBUTES.
    • OTEL_RESOURCE_ATTRIBUTES: il valore include k8s.pod.uid=$(K8S_POD_UID) per consentire al processore degli attributi Kubernetes di associare i metadati, come k8s.namespace.name, k8s.deployment.name e k8s.node.name, ai pod hostNetwork. L'associazione di metadati e pod hostNetwork consente di aggiungere i metadati estratti a span, metriche e log come attributi delle risorse.
  • Prompt e risposte.
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl': indica a OpenTelemetry di formattare gli oggetti Cloud Storage come JSON Lines. Questa variabile di ambiente ha un valore fisso: jsonl.
    • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload': indica a OpenTelemetry di caricare i dati di prompt e risposta anziché incorporare questi contenuti negli intervalli di traccia. I riferimenti agli oggetti caricati sono inclusi in una voce di log. Questa variabile di ambiente ha un valore fisso: upload.
    • OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental': indica a OpenTelemetry di utilizzare le convenzioni semantiche più recenti per l'AI generativa. Questa variabile di ambiente ha un valore fisso: gen_ai_latest_experimental.
    • OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH: specifica il percorso degli oggetti. Ad esempio, gs://STORAGE_BUCKET_NAME/PATH

Configurazione manuale

Esistono diversi metodi che puoi utilizzare per configurare un workload in modo che invii indicatori all'endpoint del raccoglitore gestito. Se configuri manualmente il workload, puoi aggiungere e modificare manualmente le variabili di ambiente oppure utilizzare un altro metodo, ad esempio i flag della riga di comando.

Sconsigliamo di utilizzare la configurazione manuale e quella automatica 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.

Per maggiori dettagli sulla configurazione automatica, consulta Configurazione automatica.

Workload supportati

I workload supportati sono quelli che utilizzano OpenTelemetry per raccogliere dati sul comportamento di runtime dell'applicazione. I workload supportano in modo nativo OpenTelemetry se utilizzano l'SDK OpenTelemetry e sono configurati utilizzando le variabili di ambiente OpenTelemetry standard. Ad esempio, l'Agent Development Kit (ADK) supporta in modo nativo OpenTelemetry.

Per maggiori dettagli su come vengono generati e raccolti i dati sul comportamento di runtime della tua applicazione, consulta Osservabilità per gli sviluppatori di applicazioni.

Se un workload supporta alcuni tipi di dati OTLP e non altri, Managed OpenTelemetry per GKE raccoglie i dati OTLP. Ad esempio, se un workload utilizza l'SDK OpenTelemetry per implementare le tracce, ma non lo utilizza per i log o le metriche, i dati dei log e delle metriche non vengono raccolti da Managed OpenTelemetry per GKE. Per informazioni dettagliate su come controllare il tipo di dati da raccogliere, consulta Seleziona i tipi di indicatori da raccogliere.

L'inserimento della configurazione OpenTelemetry non è supportato per i workload con privilegi dei partner GKE Autopilot.

Fatturazione

Quando invii dati di telemetria a Google Cloud, ti viene addebitato il volume di importazione. Le metriche vengono fatturate in base ai prezzi di Google Cloud Managed Service per Prometheus, i log in base ai prezzi di Cloud Logging e le tracce in base ai prezzi di Cloud Trace.

Per informazioni sui costi associati all'importazione di tracce, log e metriche di Google Cloud Managed Service per Prometheus, consulta Prezzi di Google Cloud Observability.

Quote

Quando utilizzi OpenTelemetry gestito per GKE, si applicano le quote per i servizi di Google Cloud Observability. Per maggiori dettagli, consulta le seguenti sezioni:

Passaggi successivi