Panoramica degli esempi di strumentazione basata su collector

Questo documento descrive la struttura degli esempi di instrumentazione forniti per i linguaggi Go, Java, Node.js e Python. Questi esempi forniscono indicazioni su come instrumentare un'applicazione per utilizzare l'SDK OpenTelemetry e un agente di raccolta OpenTelemetry.

L'instrumentazione in questi esempi, che include l'utilizzo dell'SDK OpenTelemetry e dell'esportatore OTLP in-process dell'SDK, è indipendente dal fornitore. L'esportatore in-process invia i dati di telemetria all'agente di raccolta OpenTelemetry, che li riceve e li invia al tuo Google Cloud progetto. L'agente di raccolta contiene l'associazione a Google Cloud. Questi esempi utilizzano gli Google Cloud esportatori per inviare i dati di log e metriche al tuo progetto. Tuttavia, inviano i dati di traccia al tuo progetto utilizzando l'API Telemetry.

Potresti essere interessato ad altri esempi che illustrano configurazioni diverse:

Eseguire la migrazione dall'esportatore Trace all'endpoint OTLP descrive come utilizzare l'instrumentazione in-process per inviare i dati di traccia direttamente al 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 traccia 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.

Come funzionano gli esempi

Gli esempi per Go, Java, Node.js e Python utilizzano il protocollo OpenTelemetry per raccogliere i dati di traccia e metriche. Gli esempi configurano un framework di logging per scrivere log strutturati e l' agente di raccolta OpenTelemetry è configurato per leggere dallo stream stdout dell'applicazione. Per i consigli sui framework, consulta Scegliere un approccio di instrumentazione.

Le applicazioni vengono create e implementate utilizzando Docker. Non devi utilizzare Docker quando instrumenti 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 vengono poi inviati al tuo Google Cloud progetto utilizzando un Google Cloud esportatore. L'esportatore converte i dati di telemetria in un formato compatibile con l'Cloud Trace API, l'API Cloud Monitoring o l'API Cloud Logging. Poi, inviano i dati trasformati al tuo Google Cloud progetto emettendo un comando API.

Gli esempi mostrano come eseguire le seguenti operazioni:

Configurare OpenTelemetry per raccogliere metriche e tracce utilizzando il OpenTelemetry Collector.

Se esamini gli esempi, noterai che la complessità di questo passaggio dipende dal linguaggio. Ad esempio, per Go, questo passaggio configura la funzione main per chiamare una funzione che configura la raccolta di metriche e tracce. Per Go, vengono aggiornati anche il server e il client HTTP.
Configurare un framework di logging per scrivere log strutturati.

Ti consigliamo di scrivere log strutturati nelle tue applicazioni, in modo che il payload dei log venga formattato 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 progetto. Google Cloud Altri servizi, come Compute Engine, richiedono l'installazione di un agente che esegue lo scraping e l'invio dei log. Se vuoi scoprire di più sugli agenti che installi, consulta la panoramica di Ops Agent.

Non devi installare alcun agente per utilizzare questi esempi.
Configurare i file Docker. Tutti gli esempi contengono i seguenti file YAML:
- docker-compose.yaml: configura i servizi per l'applicazione, 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 ambiente OTEL_EXPORTER_OTLP_ENDPOINT, specificata nel servizio app.
- otel-collector-config.yaml: configura OpenTelemetry Collector. Questo agente di raccolta specifica ricevitori, esportatori, processori e pipeline.
  
  Il servizio telemetry definisce le pipeline per i dati di traccia, metriche e log. Ogni voce della pipeline specifica un ricevitore, un processore e un esportatore. Lo stesso ricevitore, otlp, viene utilizzato per metriche e tracce.
  
  La sezione exporters descrive come i dati raccolti vengono esportati in un Google Cloud progetto. Per i dati di log e metriche, Google Cloud vengono utilizzati gli esportatori. Questi esportatori convertono i dati di telemetria in un formato compatibile con l'API corrispondente e poi inviano i dati trasformati al tuo Google Cloud progetto emettendo un comando API. Al contrario, i dati di traccia vengono inviati al tuo progetto utilizzando l'API Telemetry, che supporta OTLP.
- docker-compose.creds.yaml: questo file monta facoltativamente un Google Cloud file delle credenziali nel otelcol container. Questo file è necessario quando un esempio viene eseguito 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 le applicazioni di esempio per scrivere dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo progetto:
- Scrittore log (roles/logging.logWriter)
- Scrittore metriche Monitoring (roles/monitoring.metricWriter)
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
Se esegui gli esempi in Cloud Shell, sulle Google Cloud risorse, o in un ambiente di sviluppo locale, le autorizzazioni precedenti sono sufficienti per scrivere dati di log, metriche e tracce. Per le applicazioni di produzione, in genere un account di servizio fornisce le credenziali richieste.

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.

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 del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l' serviceusage.services.enable autorizzazione. Scopri come concedere i ruoli.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Passaggi successivi

Per saperne di più sugli agenti di raccolta, consulta OpenTelemetry Collector creato da Google.

Esplora gli esempi che utilizzano le esportazioni basate su agenti di raccolta.