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 esportatori per inviare i dati di log e delle metriche al tuo progetto. Tuttavia, inviano 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 esemplare è un punto dati di esempio collegato 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 strumentazione.

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

Puoi eseguire gli esempi in Cloud Shell, sulle risorse Google Cloudo in un ambiente di sviluppo locale.

Approfondimento

Gli esempi utilizzano OpenTelemetry Collector come sidecar per ricevere e arricchire la telemetria dell'applicazione, che viene poi inviata al tuo progettoGoogle Cloud utilizzando un Google Cloud esportatore. L'esportatore converte la telemetria in un formato compatibile con l'Cloud Trace API, l'API Cloud Monitoring o l'API Cloud Logging. Successivamente, inviano i dati trasformati al tuo progettoGoogle Cloud emettendo un comando API.

Gli esempi mostrano come:

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

    Se esamini gli esempi, noterai che 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 nelle tue applicazioni, in modo che il payload del log venga formattato come oggetto JSON. Per questi log, puoi creare query che cercano 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. Se vuoi saperne di più sugli agenti che installi, consulta la panoramica di Ops Agent.

    Non è necessario installare agenti per utilizzare questi esempi.

  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 collettore OpenTelemetry è impostato dalla variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT, specificata nel servizio app.

    • otel-collector-config.yaml: configura il collettore OpenTelemetry. Questo collettore 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 progetto Google Cloud . Per i dati di log e delle metriche, vengono utilizzati gli esportatoriGoogle Cloud . Questi esportatori convertono la telemetria in un formato compatibile con l'API corrispondente e poi inviano i dati trasformati al tuo progettoGoogle Cloud 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 file di credenzialiGoogle Cloud nel contenitore otelcol. Questo file è necessario quando un campione 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 consentire alle applicazioni di esempio di scrivere dati di log, metriche e traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Se esegui gli esempi in Cloud Shell, sulle risorse Google Cloud o in un ambiente di sviluppo locale, le autorizzazioni precedenti sono sufficienti per scrivere dati di log, metriche e traccia. Per le applicazioni di produzione, un account di servizio in genere fornisce le credenziali richieste.

API obbligatorie

Enable the Cloud Logging, Cloud Monitoring, Cloud Trace, and Telemetry APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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 sul raccoglitore.