Questa pagina è stata tradotta dall'API Cloud Translation.

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.

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

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 l'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 valore rappresentativo è 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 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:

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

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 traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel 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 traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel 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.

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.

Enable the APIs

Google Cloud CLI