Panoramica degli esempi di strumentazione

Questo documento descrive la struttura degli esempi di ispezione forniti per i linguaggi Go, Java, Node.js e Python. Questi esempi forniscono indicazioni su come eseguire l'instrumentazione di un'applicazione.

Potresti essere interessato ad altri esempi che illustrano configurazioni diverse:

Come funzionano i sample

Gli esempi per Go, Java, Node.js e Python utilizzano il protocollo OpenTelemetry per raccogliere i dati delle tracce e delle metriche. I sample configurano un framework di logging per scrivere log strutturati e il collezionista OpenTelemetry è configurato per leggere da lo stream stdout dell'applicazione. Per i consigli sui framework, consulta Scegliere un approccio di misurazione.

Le applicazioni vengono create e implementate utilizzando Docker. Non è necessario utilizzare Docker quando esegui l'instrumentazione di un'applicazione con OpenTelemetry.

Puoi eseguire i sample in Cloud Shell, su Google Cloud risorse o in un ambiente di sviluppo locale.

Approfondimento

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

Gli esempi mostrano come eseguire le seguenti operazioni:

  1. Configura OpenTelemetry per raccogliere metriche e tracce utilizzando il collezionista OpenTelemetry.

    Se esamini i sample, noterai che la complessità di questo passaggio dipende dalla lingua. Ad esempio, per Go, questo passaggio configura la funzione main in modo che chiami 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 sia formattato come oggetto JSON. Per questi log, puoi costruire query che cercano 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 invia i log. Per informazioni sugli agenti che installi, consulta la Panoramica di Ops Agent.

    Non è necessario installare agenti per utilizzare questi esempi.

  3. Configura i file Docker. Tutti i sample 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 collector OpenTelemetry, otelcol, specifica un'immagine, un volume e le variabili di ambiente. L'endpoint per il collector OpenTelemetry viene impostato dalla variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT, specificata nel servizio app.

    • otel-collector-config.yaml: configura i ricevitori, gli esportatori, i processori e le pipeline.

      Il servizio telemetry definisce le pipeline per i dati di traccia, metriche e log. Ogni voce della pipeline specifica un destinatario, un elaboratore e un esportatore. Lo stesso destinatario, otlp, viene utilizzato per le metriche e le tracce.

      La sezione exporters descrive come vengono esportati i dati raccolti in un progetto Google Cloud. Per tutta la telemetria viene utilizzato un Google Cloud esportatore. L'esportatore converte la telemetria in un formato compatibile con l'API Cloud Trace, l'API Cloud Monitoring o l'API Cloud Logging. Successivamente, invia i dati trasformati al progetto Google Cloud emettendo un comando API.

    • docker-compose.creds.yaml: questo file monta facoltativamente un Google Cloud file delle credenziali nel contenitore otelcol. Questo file è necessario quando un sample viene eseguito su una macchina locale in cui le credenziali predefinite dell'applicazione (ADC) sono disponibili solo come file.

Autorizzazioni obbligatorie

Se esegui i sample in Cloud Shell, su risorse Google Cloudo in un ambiente di sviluppo locale, le autorizzazioni elencate in questa sezione sono sufficienti. Per le applicazioni di produzione, in genere un account di servizio fornisce le credenziali per scrivere i dati di log, metriche e traccia.

  • 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:

API obbligatorie

Di seguito sono riportate informazioni sulle API necessarie per inviare dati di telemetria a un progetto Google Cloud:

Console Google Cloud

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Google Cloud CLI

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

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

Passaggi successivi