Scegliere un approccio di strumentazione

Puoi scegliere l'approccio di instrumentazione più efficace per la tua applicazione in base alla tua Google Cloud piattaforma di calcolo e ai requisiti di telemetria. Questa guida fornisce consigli per Google Kubernetes Engine (GKE), Compute Engine e Cloud Run, aiutandoti a scegliere tra Google-Built OpenTelemetry Collector, Ops Agent ed esportazione OpenTelemetry diretta in-process.

Questo documento fornisce consigli generali, nonché indicazioni per le seguenti piattaforme:

• GKE
• Compute Engine
• Cloud Run
• Cloud Run Functions
• App Engine

Per le applicazioni di esempio, consulta Esempi e guide di implementazione.

I consigli riportati in questa pagina non sono le uniche soluzioni e possono funzionare anche altri approcci. Per ulteriori indicazioni, contatta l'assistenza clienti Google Cloud.

Consigli generali

Questa sezione contiene consigli generali su come instrumentare l'applicazione. Per indicazioni specifiche per la piattaforma, consulta Consigli sulla piattaforma.

• Dati di log: ti consigliamo di utilizzare un framework che possa essere configurato per generare log strutturati in formato JSON per Cloud Logging. Per la scrittura dei dati di log, ti consigliamo di:

  • Go: slog.
  • Python: logging.
  • JavaScript: Pino.
  • Java: SLF4J con Log4j2.

• Dati delle metriche: ti consigliamo di utilizzare le librerie client OpenTelemetry o Prometheus:

  • OpenTelemetry fornisce un framework open source indipendente dal fornitore e librerie client per instrumentare le applicazioni per le metriche.
  • Le librerie client Prometheus (Go, Java, Python e così via) generano metriche che possono essere esposte in un endpoint HTTP ed eseguite da un agente.

• Dati di Trace: ti consigliamo di utilizzare OpenTelemetry per generare dati di traccia distribuiti dal codice dell'applicazione.

Architetture di raccolta OpenTelemetry

Quando instrumenti un'applicazione con le librerie OpenTelemetry, puoi indirizzare la telemetria tramite OpenTelemetry Collector autonomo o esportare direttamente dal processo dell'applicazione. Il file di configurazione di OpenTelemetry Collector controlla la modalità di ricezione, elaborazione ed esportazione della telemetria da parte del raccoglitore. In generale, ti consigliamo di configurare i raccoglitori in modo che ricevano ed esportino la telemetria utilizzando OpenTelemetry Protocol (OTLP). L'API Telemetry (OTLP) implementa questo protocollo.

Esistono due approcci fondamentali per l'invio della telemetria al tuo Google Cloud progetto:

• Esportazione basata sul raccoglitore (indipendente dal fornitore): instrumenti il codice dell'applicazione con l'SDK OpenTelemetry e utilizzi l'esportatore OTLP in-process per inviare i dati a un raccoglitore OpenTelemetry, come Google-Built OpenTelemetry Collector o un ricevitore Ops Agent. L'agente di raccolta riceve la telemetria e la inoltra al tuo Google Cloud progetto. Il codice dell'applicazione rimane completamente indipendente dal fornitore.

• Esportazione diretta (specifica del fornitore): instrumenti il codice dell'applicazione con l'SDK OpenTelemetry e configuri OpenTelemetry per inviare la telemetria al tuo progetto utilizzando l'API Telemetry. Non è necessario fare il deployment di un agente di raccolta, ma il codice dell'applicazione include dipendenze specifiche del fornitore.

Ti consigliamo di utilizzare un agente di raccolta OpenTelemetry quando l'ambiente di calcolo ne supporta uno. Per gli ambienti in cui l'esecuzione di un processo di raccolta separato non è pratica, utilizza l'esportazione diretta in-process.

Consigli sulla piattaforma

Poiché Google Cloud gli ambienti di calcolo hanno un ciclo di vita e funzionalità sidecar diversi, il pattern di raccolta ottimale varia in base alla piattaforma. Le sezioni seguenti forniscono consigli specifici per l'ambiente di deployment.

GKE

Per informazioni generali su GKE, consulta Panoramica di GKE.

Tipo	Suggerimento
Metriche	Ti consigliamo di utilizzare Google Cloud Managed Service per Prometheus. Per l'instrumentazione, esegui una delle seguenti operazioni: Utilizza le librerie client Prometheus. Se utilizzi questo approccio, ti consigliamo anche di utilizzare la raccolta gestita, che include le istruzioni di installazione dell'esportatore tramite copia e incolla per le applicazioni comuni. Utilizza le librerie OpenTelemetry e OpenTelemetry Collector: Esegui il deployment di Google-Built OpenTelemetry Collector su Google Kubernetes Engine. Utilizza l' SDK OpenTelemetry e l'esportatore OTLP per il tuo linguaggio. L'agente di raccolta riceve i dati delle metriche dall'esportatore OTLP in-process dell'SDK, li elabora e li esporta. Assicurati che tu configuri l'agente di raccolta in modo che esporti i dati delle metriche in Managed Service per Prometheus. Per saperne di più, consulta la guida introduttiva a OpenTelemetry Collector.
Tracce	Segui questi passaggi: Esegui il deployment di Google-Built OpenTelemetry Collector su Google Kubernetes Engine. L'agente di raccolta riceve i dati di traccia dall'esportatore OTLP in-process dell'SDK, li elabora e li invia al tuo Google Cloud progetto utilizzando l'API Telemetry (OTLP). Utilizza l' SDK OpenTelemetry e l'esportatore OTLP per il tuo linguaggio.
Log	Configura l'app in modo che generi log strutturati in formato JSON in stdout e stderr. Per un elenco dei framework, consulta Framework di logging consigliati. GKE raccoglie automaticamente i log scritti in stdout e stderr. Per saperne di più, consulta Informazioni sui log di GKE.

Compute Engine

Per informazioni generali su Compute Engine, consulta Istanze di macchine virtuali.

Tipo	Suggerimento
Metriche e tracce	Segui questi passaggi: Utilizza Ops Agent per raccogliere metriche e tracce. Per un esempio, consulta Raccogliere metriche e tracce OpenTelemetry Protocol (OTLP). Questa guida descrive come configurare Ops Agent per ricevere dati di metriche e tracce dagli esportatori OTLP in-process dell'SDK, trasformarli, e inviarli al tuo Google Cloud progetto. I dati delle metriche vengono inviati utilizzando l'API Cloud Monitoring e i dati di traccia vengono inviati utilizzando l'Cloud Trace API. Utilizza l' SDK OpenTelemetry e l'esportatore OTLP per il tuo linguaggio. In alternativa, se vuoi configurare la raccolta solo per le metriche in formato Prometheus, utilizza il ricevitore Prometheus di Ops Agent per raccogliere le metriche instrumentate utilizzando le librerie client Prometheus o l'SDK OpenTelemetry.
Log	Segui questi passaggi: Configura l'app in modo che generi log strutturati in formato JSON in un file. Per un elenco dei framework, consulta Framework di logging consigliati. Installa Ops Agent e configura un ricevitore. Per un esempio, consulta Ricevitori di logging.

Cloud Run

Per informazioni generali su Cloud Run, consulta Che cos'è Cloud Run.

Tipo	Suggerimento
Metriche e tracce	Segui questi passaggi: Utilizza l' SDK OpenTelemetry e l'esportatore OTLP per il tuo linguaggio. Esegui il deployment di un sidecar OpenTelemetry per raccogliere metriche e tracce. Per esempi, consulta i seguenti documenti: Scrivere metriche OTLP utilizzando un sidecar OpenTelemetry. Eseguire il deployment di Google-Built OpenTelemetry Collector su Cloud Run. Il raccoglitore riceve i dati di log, metriche e tracce da gli esportatori OTLP in-process dell'SDK e li trasforma. Poi, esporta i dati delle metriche utilizzando l' googlemanagedprometheus esportatore ed esporta i dati di log e metriche utilizzando gli Google Cloud esportatori. Per il servizio Cloud Run, utilizza la fatturazione basata sulle istanze. Con la fatturazione basata sulle istanze, la CPU viene allocata per l'intero ciclo di vita dell'istanza, il che è necessario perché l'instrumentazione OpenTelemetry esegue l'elaborazione in background. Per saperne di più, consulta Impostazioni di fatturazione per i servizi Cloud Run. In alternativa, se vuoi configurare la raccolta solo per le metriche in formato Prometheus, utilizza il sidecar Prometheus per Cloud Run per raccogliere le metriche instrumentate utilizzando le librerie client Prometheus o l'SDK OpenTelemetry.
Log	Configura l'app in modo che generi log strutturati in formato JSON in stdout e stderr. Per un elenco dei framework, consulta Framework di logging consigliati. Cloud Run raccoglie automaticamente i log scritti in stdout e stderr. Per saperne di più, consulta Scrivere log dei container.

Cloud Run Functions

Per informazioni generali su Cloud Run Functions, consulta Panoramica di Cloud Run Functions.

Tipo	Suggerimento
Metriche	La scrittura diretta dei dati delle metriche non è supportata in Cloud Run Functions. Puoi generare metriche basate sui log.
Tracce	Utilizza l'SDK OpenTelemetry e l'esportatore Cloud Trace per il tuo linguaggio.
Log	Configura l'app in modo che generi log strutturati in formato JSON in stdout e stderr. Per un elenco dei framework, consulta Framework di logging consigliati. Cloud Run Functions raccoglie automaticamente i log scritti in stdout e stderr. Per saperne di più, consulta Cloud Run Functions: panoramica di monitoraggio e logging.

App Engine

Per informazioni generali su App Engine, consulta Panoramica di App Engine.

Tipo	Suggerimento
Metriche	Utilizza l' SDK OpenTelemetry e l'esportatore Cloud Monitoring per il tuo linguaggio.
Tracce	Utilizza l'SDK OpenTelemetry e l'esportatore Cloud Trace per il tuo linguaggio.
Log	Configura l'app in modo che generi log strutturati in formato JSON in stdout e stderr. Per un elenco dei framework, consulta Framework di logging consigliati. App Engine raccoglie automaticamente i log scritti in stdout e stderr. Per saperne di più, consulta Scrivere e visualizzare i log.

Esempi e guide di implementazione

• La panoramica degli esempi descrive l'architettura e i ruoli Identity and Access Management richiesti per i seguenti esempi di codice basati sul raccoglitore:

  • Go
  • Java
  • Node.js
  • Python

• Eseguire la migrazione dall'esportatore Trace all'endpoint OTLP descrive come aggiornare un'applicazione che utilizza l'esportazione diretta per inviare dati di traccia in formato OTLP.

• Instrumentare le applicazioni di AI generativa descrive come instrumentare o abilitare gli agenti di AI generativa creati con LangGraph o il framework Agent Development Kit (ADK).

Documentazione di OpenTelemetry

Questa sezione fornisce link all'SDK OpenTelemetry e agli esportatori per OTLP, Cloud Trace e Cloud Monitoring.

Riferimenti generali:

• API e SDK in più linguaggi
• Esportatore OTLP

Go

• SDK Go
• Esportatore OTLP Go
• Esportatore Cloud Trace Go
• Esportatore Cloud Monitoring Go

Java

• SDK Java
• Esportatore OTLP Java
• Esportatore Cloud Trace Java
• Esportatore Cloud Monitoring Java

JavaScript

• SDK JavaScript
• Esportatore OTLP JavaScript
• Esportatore Cloud Trace JavaScript
• Esportatore Cloud Monitoring JavaScript

Python

• SDK Python
• Esportatore OTLP Python
• Esportatore Cloud Trace Python
• Esportatore Cloud Monitoring Python