Per mantenere il codice dell'applicazione indipendente dal fornitore durante la raccolta e l'invio di dati di telemetria a Google Cloud, puoi utilizzare gli esempi di strumentazione basati sul raccoglitore OpenTelemetry per Go, Java, Node.js e Python.
Questi esempi mostrano come configurare un SDK OpenTelemetry in-process per esportare metriche, log e tracce in un raccoglitore OpenTelemetry locale che instrada i dati di telemetria a Google Cloud. Gli esempi inviano dati di metriche e tracce in formato OpenTelemetry Protocol (OTLP) al tuo Google Cloud progetto utilizzando l' API Telemetry e inviano dati di log utilizzando un Google Cloud esportatore.
Come funzionano gli esempi
Gli esempi per Go, Java, Node.js e Python utilizzano il
protocollo OpenTelemetry per raccogliere dati di tracce e metriche.
Gli esempi configurano un framework di logging per scrivere
log strutturati e configurano l'agente di raccolta
OpenTelemetry per leggere da
stream stdout dell'applicazione. Per i consigli sui framework, consulta
Scegliere un approccio di strumentazione.
Le applicazioni vengono create e di cui viene eseguito il deployment utilizzando Docker. Non devi utilizzare Docker quando strumenti un'applicazione con OpenTelemetry.
Puoi eseguire gli esempi in Cloud Shell, sulle Google Cloud risorse o in un ambiente di sviluppo locale.
Approfondimento
Gli esempi utilizzano OpenTelemetry Collector come sidecar per ricevere e arricchire i dati di telemetria dell'applicazione, che un esportatore invia poi al tuo Google Cloud progetto. Le applicazioni di esempio inviano dati di metriche e tracce al tuo progetto utilizzando l'API Telemetry, che supporta il formato OTLP.
Gli esempi mostrano come eseguire le seguenti operazioni:
Configura OpenTelemetry per raccogliere metriche e tracce utilizzando il OpenTelemetry collector.
La complessità di questo passaggio dipende dalla lingua. Ad esempio, in Go, aggiorna la funzione
mainper inizializzare la raccolta dei dati di telemetria e configurare il server e il client HTTP.Configura un framework di logging per scrivere log strutturati.
Ti consigliamo di scrivere log strutturati nelle tue applicazioni, che formattano il payload dei log come oggetto JSON. Per questi log, puoi creare query che cercano percorsi JSON specifici e puoi indicizzare campi specifici nel payload dei log.
Alcuni servizi, come Google Kubernetes Engine, hanno agenti integrati che eseguono lo scraping dei log strutturati e li inviano al tuo Google Cloud progetto. Altri servizi, come Compute Engine, richiedono l'installazione di un agente che esegue lo scraping e l'invio dei log. Per scoprire di più sugli agenti che installi, consulta la panoramica di Ops Agent.
Non devi installare alcun agente per utilizzare questi esempi.
Configura i file Docker. Tutti gli esempi contengono i seguenti file YAML:
docker-compose.yaml: configura i servizi per l'applicazione, il OpenTelemetry Collector e un generatore di carico. Ad esempio, il servizio per OpenTelemetry Collector,otelcol, specifica un'immagine, un volume e le variabili di ambiente. L'endpoint per OpenTelemetry Collector è impostato dalla variabile di ambienteOTEL_EXPORTER_OTLP_ENDPOINT, specificata nel servizioapp.otel-collector-config.yaml: configura OpenTelemetry Collector:Gli esempi utilizzano il ricevitore
otlpper i dati di metriche e tracce e il ricevitorefilelogper i dati di log.Gli esempi utilizzano l'esportatore
otlphttpper i dati di metriche e tracce, e l' Google Cloud esportatore per i dati di log.L'esportatore
otlphttpinvia i dati al tuo progetto utilizzando l'API Telemetry, che supporta OTLP. L' Google Cloud esportatore converte i dati di log in un formato compatibile con l' API Cloud Logging e poi invia i dati trasformati al tuo Google Cloud progetto.
docker-compose.creds.yaml: questo file monta facoltativamente un Google Cloud file di credenziali nelotelcolcontainer. Questo file è necessario quando esegui un esempio su una macchina locale in cui le credenziali predefinite dell'applicazione (ADC) sono disponibili solo come file.
Autorizzazioni obbligatorie
-
Per ottenere le autorizzazioni necessarie per consentire alle applicazioni di esempio di scrivere dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Scrittore log (
roles/logging.logWriter) sul tuo progetto - Scrittore metriche Monitoring (
roles/monitoring.metricWriter) sul tuo progetto - Cloud Telemetry Traces Writer (
roles/telemetry.tracesWriter) sul tuo progetto - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer) sul tuo progetto di quota
Queste autorizzazioni sono sufficienti se esegui l'esempio in Cloud Shell, sulle Google Cloud risorse o in un ambiente di sviluppo locale. Per scoprire come configurare un progetto di quota, consulta Impostare il progetto di quota.
- Scrittore log (
-
Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo progetto:
- Visualizzatore log (
roles/logging.viewer) - Visualizzatore Monitoring (
roles/monitoring.viewer) - Utente Cloud Trace (
roles/cloudtrace.user)
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.
- Visualizzatore log (
API obbligatorie
Abilita le API Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry:
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 utilizzo servizi (roles/serviceusage.serviceUsageAdmin).
Scopri come concedere i ruoli.
gcloud services enable logging.googleapis.commonitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com
Approcci di strumentazione alternativi
Potresti essere interessato ad altri esempi che illustrano configurazioni diverse:
Eseguire la migrazione dall'esportatore di Trace all'endpoint OTLP descrive come utilizzare la strumentazione in-process per inviare i dati di traccia direttamente a tuo Google Cloud progetto.
Ti consigliamo di utilizzare un agente di raccolta OpenTelemetry per esportare i dati di telemetria quando il tuo ambiente supporta l'utilizzo di un agente di raccolta. Se non puoi utilizzare un agente di raccolta, devi utilizzare un esportatore in-process che invia direttamente i dati al tuo Google Cloud progetto.
Correlare metriche e tracce utilizzando gli esemplari descrive come configurare un'applicazione Go per generare esemplari. Un esemplare è un punto dati di esempio collegato a un punto dati di metrica. Puoi utilizzare gli esemplari per correlare i dati di tracce e metriche.
Utilizzare Ops Agent e OpenTelemetry Protocol (OTLP) descrive come configurare Ops Agent e un ricevitore OTLP per raccogliere metriche e tracce da un'applicazione.
Passaggi successivi
Per scoprire di più sugli agenti di raccolta, consulta Agente di raccolta OpenTelemetry integrato in Google.
Esplora gli esempi che utilizzano le esportazioni basate sul raccoglitore.