Panoramica degli esempi di strumentazione basata su collector

Questo documento descrive la struttura degli esempi di strumentazione 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 collettore OpenTelemetry.

La strumentazione 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 la telemetria all'agente di raccolta OpenTelemetry, che riceve i dati e li invia al tuo progetto Google Cloud . Il raccoglitore contiene l'associazione a Google Cloud. Questi esempi utilizzano Google Cloud gli esportatori per inviare i dati di log e delle metriche al tuo progetto. Tuttavia, inviano i dati di traccia al tuo progetto utilizzando l'API Telemetry.

Potrebbero interessarti 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 al tuo progetto Google Cloud .

    Ti consigliamo di utilizzare un raccoglitore OpenTelemetry per esportare i dati di telemetria quando il tuo ambiente supporta l'utilizzo di un raccoglitore. Se non puoi utilizzare un collettore, devi utilizzare un esportatore in-process che invia direttamente i dati al tuo progetto Google Cloud .

  • Correlare metriche e tracce utilizzando gli esemplari descrive come configurare un'applicazione Go per generare esemplari. Un campione è un punto dati di esempio allegato a un punto dati della metrica. Puoi utilizzare gli esemplari per correlare i dati di traccia e delle 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 dati di traccia e metriche. Gli esempi configurano un framework di logging per scrivere log strutturati e il collettore OpenTelemetry è configurato per leggere dal flusso stdout dell'applicazione. Per i consigli sui framework, vedi Scegliere un approccio di instrumentazione.

Le applicazioni vengono create e di cui viene eseguito il deployment utilizzando Docker. Non è necessario utilizzare Docker quando instrumenti un'applicazione con OpenTelemetry.

Puoi eseguire gli esempi in Cloud Shell, sulle risorse Google Cloud 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 progetto Google Cloud . 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:

  1. Configura OpenTelemetry per raccogliere metriche e tracce utilizzando OpenTelemetry Collector.

    La complessità di questo passaggio dipende dalla lingua. 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.

  2. Configura un framework di logging per scrivere log strutturati.

    Ti consigliamo di scrivere log strutturati, che formattano il payload del log come oggetto JSON. Per questi log, puoi creare query che cerchino percorsi JSON specifici e puoi indicizzare campi specifici nel payload del 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. Per scoprire di più sugli agenti che installi, consulta Panoramica di Ops Agent.

    Per utilizzare questi esempi, non è necessario installare alcun agente.

  3. Configura i file Docker. Tutti gli esempi contengono i seguenti file YAML:

    • docker-compose.yaml: configura i servizi per l'applicazione, il collettore OpenTelemetry e un generatore di carico. Ad esempio, il servizio per il collettore OpenTelemetry, otelcol, specifica un'immagine, un volume e variabili di ambiente. L'endpoint per il raccoglitore OpenTelemetry è impostato dalla variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT, specificata nel servizio app.

    • otel-collector-config.yaml: configura OpenTelemetry:

      • Gli esempi utilizzano il ricevitore otlp per i dati di metrica e traccia e il ricevitore filelog per i dati di log.

      • Gli esempi utilizzano l'esportatore otlphttp per i dati di metriche e tracce e l'esportatore Google Cloud per i dati di log.

        L'esportatore otlphttp invia i dati al tuo progetto utilizzando l'API Telemetry, che supporta OTLP. L'esportatore Google Cloud converte i dati dei log in un formato compatibile con l'API Cloud Logging e poi invia i dati trasformati al tuo progettoGoogle Cloud emettendo un comando API.

    • docker-compose.creds.yaml: questo file monta facoltativamente un file di credenziali Google Cloudnel container otelcol. Ti serve questo file quando esegui un campione 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:

    Queste autorizzazioni sono sufficienti se esegui l'esempio in Cloud Shell, sulle risorse Google Cloud o in un ambiente di sviluppo locale. Per scoprire come configurare un progetto quota, consulta Imposta il progetto quota.

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 dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli. 

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

Passaggi successivi

Per scoprire di più sui raccoglitori, consulta Raccoglitore OpenTelemetry creato da Google.

Esplora gli esempi che utilizzano le esportazioni basate su raccoglitore.