Per mantenere il codice dell'applicazione indipendente dal vendor durante la raccolta e l'invio di dati di telemetria a Google Cloud, puoi utilizzare gli esempi di strumentazione basata su collector 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 indirizza la telemetria a Google Cloud. Gli esempi inviano dati di log, metriche e tracce in formato OpenTelemetry Protocol (OTLP) al tuo progetto Google Cloud utilizzando l'API Telemetry.
Come funzionano gli esempi
Gli esempi per Go, Java, Node.js e Python utilizzano il protocollo OpenTelemetry per raccogliere i dati di tracce e metriche.
Gli esempi configurano un framework di logging per scrivere log strutturati e configurano il raccoglitore OpenTelemetry per leggere dallo stream stdout dell'applicazione. Per i consigli sui framework, consulta
Scegli un approccio di strumentazione.
Le applicazioni vengono create e ne viene eseguito il deployment utilizzando Docker. Non è necessario utilizzare Docker quando instrumenti un'applicazione con OpenTelemetry.
Puoi eseguire gli esempi in Cloud Shell, su risorse Google Cloud o in un ambiente di sviluppo locale.
Approfondimento
Gli esempi utilizzano OpenTelemetry Collector come sidecar per ricevere e arricchire la telemetria dell'applicazione, che un esportatore invia poi al tuo progetto Google Cloud . Gli esempi inviano dati di log, metriche e tracce al tuo progetto utilizzando l'API Telemetry, che supporta il formato OTLP.
Gli esempi mostrano come:
Configura OpenTelemetry per raccogliere metriche e tracce utilizzando il raccoglitore OpenTelemetry.
La complessità di questo passaggio dipende dalla lingua. Ad esempio, in Go, aggiorni la funzione
mainper inizializzare la raccolta della telemetria e configurare il server e il client HTTP.Configura un framework di logging per scrivere log strutturati.
Ti consigliamo di scrivere log strutturati per le tue applicazioni, che formattano il payload del log come oggetto JSON. Per questi log, puoi creare query che eseguono ricerche in percorsi JSON specifici e puoi indicizzare campi specifici nel payload del log.
Alcuni servizi, come Google Kubernetes Engine, dispongono di agenti integrati che eseguono lo scraping dei log strutturati e li inviano al tuo progetto Google Cloud . 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 è necessario 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 raccoglitore OpenTelemetry e un generatore di carico. Ad esempio, il servizio per il raccoglitore OpenTelemetry,otelcol, specifica un'immagine, un volume e variabili di ambiente. L'endpoint per il raccoglitore OpenTelemetry è impostato dalla variabile di ambienteOTEL_EXPORTER_OTLP_ENDPOINT, specificata nel servizioapp.otel-collector-config.yaml: configura il raccoglitore OpenTelemetry:Gli esempi utilizzano il receiver
otlpper i dati di metriche e tracce e il receiverfilelogper i dati di log.Gli esempi utilizzano l'esportatore
otlphttpper i dati di log, metriche e tracce.L'esportatore
otlphttpinvia i dati al tuo progetto utilizzando l'API Telemetry, che supporta OTLP.
docker-compose.creds.yaml: questo file monta facoltativamente un file di credenziali Google Cloudnel containerotelcol. 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:
- Logs Writer (
roles/logging.logWriter) sul progetto - Monitoring Metric Writer (
roles/monitoring.metricWriter) sul progetto - Cloud Telemetry Traces Writer (
roles/telemetry.tracesWriter) sul tuo progetto - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer) sul progetto di quota
Queste autorizzazioni sono sufficienti se esegui l'esempio in Cloud Shell, su risorse Google Cloud o in un ambiente di sviluppo locale. Per scoprire come configurare un progetto di quota, consulta Imposta il progetto di quota.
- Logs Writer (
-
Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
- Visualizzatore log (
roles/logging.viewer) - Monitoring Viewer (
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, 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 logging.googleapis.commonitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com
Approcci di instrumentazione alternativi
Potrebbero interessarti altri esempi che illustrano diverse configurazioni:
Esegui la migrazione dall'esportatore Trace all'endpoint OTLP descrive come utilizzare la strumentazione in-process per inviare i dati di traccia direttamente al tuo progetto Google Cloud .
Ti consigliamo di utilizzare un raccoglitore OpenTelemetry per esportare i dati di telemetria se il tuo ambiente supporta l'utilizzo di un raccoglitore. Se non puoi utilizzare un collector, devi utilizzare un exporter in-process che invia i dati direttamente al tuo progetto Google Cloud .
Correla metriche e tracce utilizzando gli exemplar descrive come configurare un'applicazione Go per generare exemplar. Un exemplar è un punto dati di esempio collegato a un punto dati della metrica. Puoi utilizzare gli exemplar per correlare i dati di tracce e metriche.
Utilizza 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ù sui raccoglitori, consulta Raccoglitore OpenTelemetry creato da Google.
Esplora gli esempi che utilizzano le esportazioni basate su raccoglitore.