Questa pagina è stata tradotta dall'API Cloud Translation.

Panoramica degli esempi di strumentazione

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.

Potrebbero interessarti altri esempi che illustrano configurazioni diverse:

Correlare metriche e tracce utilizzando gli esemplari descrive come configurare un'applicazione Go per generare esemplari. Un esemplare è 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 strumentazione.

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 Cloudo 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 progettoGoogle Cloud utilizzando un Google Cloud exporter. 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:

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.
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 recupera e invia i log. Se vuoi saperne di più sugli agenti che installi, consulta la panoramica di Ops Agent.

Non è necessario installare agenti 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 collettore 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 collettore OpenTelemetry è 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 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 tutta la telemetria, viene utilizzato un esportatore Google Cloud . L'esportatore converte la telemetria in un formato compatibile con l'Cloud Trace API, l'API Cloud Monitoring o l'API Cloud Logging. Successivamente, invia i dati trasformati al tuo progettoGoogle Cloud emettendo un comando API.
- docker-compose.creds.yaml: questo file monta facoltativamente un file di credenzialiGoogle Cloud nel container 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

Se esegui gli esempi in Cloud Shell, sulle risorse Google Cloud o 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 dati di log, metriche e traccia.

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 sul progetto:
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)
- Agente Cloud Trace (roles/cloudtrace.agent)

Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM sul 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.

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