OpenTelemetry gestito per GKE

Questo documento descrive OpenTelemetry gestito per Google Kubernetes Engine (GKE), che 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 Managed OpenTelemetry per Google Kubernetes Engine (GKE), le applicazioni devono essere già strumentate per generare segnali utilizzando il protocollo OpenTelemetry. Per maggiori dettagli, vedi Workload supportati.

OpenTelemetry gestito per GKE ha due componenti:

  • Raccolta gestita: il raccoglitore gestito fornisce un endpoint OpenTelemetry Protocol in-cluster come destinazione per i workload per inviare 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 tuoi workload GKE per generare e importare tracce, metriche e log OpenTelemetry correlati. Questo approccio supporta Agent Development Kit (ADK) e dati di prompt e risposte multimodali.

    Puoi utilizzare la risorsa personalizzata Instrumentation per i carichi di lavoro che utilizzano l'SDK OpenTelemetry e sono configurati con le variabili di ambiente OpenTelemetry standard. Questa risorsa personalizzata Instrumentation, instrumentations.telemetry.googleapis.com, è una risorsa diversa dalla risorsa Instrumentation 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 del 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 distribuite, metriche e log per il monitoraggio delle applicazioni. Per ulteriori informazioni su OpenTelemetry, consulta la documentazione su OpenTelemetry e sull'OpenTelemetry Protocol (OTLP). Per maggiori dettagli sulla generazione e sulla raccolta dei dati comportamentali di runtime della tua applicazione, vedi Instrumentazione e osservabilità.

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 nel cluster mediante il deployment di un raccoglitore OpenTelemetry gestito nel cluster. Questo endpoint OTLP in-cluster riceve tracce, metriche e log in formato OTLP. Per ricevere dati da un workload, quest'ultimo deve essere configurato per inviarli al raccoglitore.

L'endpoint del raccoglitore gestito è: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

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

Il raccoglitore gestito può essere abilitato per un cluster GKE utilizzando la console o gcloud CLI. Per istruzioni, vedi Abilitare 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 dell'agente di raccolta gestito.

Esistono diversi metodi che possono essere utilizzati per configurare un carico di lavoro. La configurazione automatica utilizza le variabili di ambiente inserite nel container del workload per fare in modo che il workload invii indicatori al collettore gestito. Se configuri manualmente il workload, puoi utilizzare altri metodi. Per maggiori dettagli, vedi 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 collettore gestito.

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

Per istruzioni su come configurare l'applicazione utilizzando la configurazione automatica, consulta Configurare l'applicazione per utilizzare il raccoglitore Managed OpenTelemetry.

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 collettore gestito.
  • Controlla la frequenza di campionamento dei dati di traccia.

Per informazioni dettagliate su come utilizzare la risorsa personalizzata Instrumentation, vedi Modificare la configurazione.

Inserisci automaticamente le variabili di ambiente

Per inserire automaticamente le variabili di ambiente OpenTelemetry nei tuoi carichi di lavoro GKE, devi configurare un oggetto Instrumentation nel tuo 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 l'applicazione viene implementata 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 un workload viene eseguito il deployment 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 dell'esportatore OpenTelemetry.
    • OTEL_EXPORTER_OTLP_ENDPOINT: un URL endpoint di base per qualsiasi tipo di segnale. Questo endpoint punta sempre all'endpoint HTTP del raccoglitore OpenTelemetry gestito nel cluster per log, metriche e tracce. L'endpoint è: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.
  • 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 è nulla 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 consecutive di metriche.
    • 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 vengono disattivati quando tracer_provider, meter_provider o logger_provider sono impostati su null nel file 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 Kubernetes Attributes Processor di OpenTelemetry Collector.
    • K8S_POD_UID: l'UID pod di un pod hostNetwork per popolare l'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 per gli oggetti. Ad esempio, gs://STORAGE_BUCKET_NAME/PATH

Configurazione manuale

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

Non è consigliabile utilizzare contemporaneamente la configurazione manuale e quella automatica per lo stesso carico di lavoro, perché la configurazione automatica può ignorare le modifiche manuali. Questa combinazione potrebbe rendere più difficile il monitoraggio delle modifiche alla configurazione.

Per maggiori dettagli sulla configurazione automatica, vedi Configurazione automatica

Workload supportati

I carichi di lavoro 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 OpenTelemetry in modo nativo.

Per maggiori dettagli su come vengono generati e raccolti i dati sul comportamento di runtime dell'applicazione, vedi Instrumentazione e osservabilità.

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 carichi di lavoro privilegiati dei partner GKE Autopilot.

Fatturazione

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

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

Quote

Quando utilizzi Managed OpenTelemetry per GKE, si applicano le quote per i servizi Google Cloud Observability. Per maggiori dettagli, vedi quanto segue:

Passaggi successivi