Questo documento descrive come modificare un'app Go per raccogliere dati di traccia e metriche utilizzando il framework open source OpenTelemetry e come scrivere log JSON strutturati allo standard out. Questo documento fornisce anche informazioni su un'app di esempio che puoi installare ed eseguire. L'app è configurata per generare metriche, tracce e log.
Per saperne di più sulla strumentazione, consulta i seguenti documenti:
Informazioni sul contesto
Il Contesto di OpenTelemetry è un meccanismo per trasportare valori basati sull'esecuzione tra le API all'interno di un processo. Un uso importante del contesto è trasferire l'intervallo attivo corrente in modo che possa essere modificato o indicato come padre di qualsiasi nuovo intervallo al momento della creazione. In sintesi:
Il contesto si riferisce al meccanismo per propagare i valori basati sull'esecuzione, incluso l'intervallo attivo corrente, tra le API all'interno di un processo.
Contesto intervallo è un oggetto immutabile in ogni intervallo che include l'ID traccia, l'ID intervallo, i flag e lo stato della traccia.
La propagazione è il meccanismo che sposta il contesto tra i servizi e i processi.
Anche la classe context.Context
della libreria standard Go trasporta valori
con ambito oltre i confini delle API. In genere, le funzioni di gestore in un server ricevono un Context
in entrata e lo trasmettono attraverso la catena di chiamate a tutti i client che effettuano richieste in uscita.
La libreria standard di Go context.Context
viene utilizzata per l'implementazione di OpenTelemetry Context in Go.
Prima di iniziare
Abilita le API Cloud Logging, Cloud Monitoring, and Cloud Trace.
Instrumenta la tua app per raccogliere tracce, metriche e log
Per consentire all'app di raccogliere dati di traccia e metriche e scrivere un file JSON strutturato in un formato standard, esegui i passaggi riportati di seguito, come descritto nelle sezioni successive di questo documento:
- Configura la funzione principale
- Configurare OpenTelemetry
- Configurare il logging strutturato
- Aggiungere la strumentazione al server HTTP
- Collega intervalli di tracce con log e metriche
- Aggiungere la strumentazione al client HTTP
- Scrivere log strutturati
Configura la funzione principale
Per configurare l'app per la scrittura di log strutturati e per la raccolta di metriche e
dati di traccia tramite OpenTelemetry, aggiorna la funzione main
per
configurare il pacchetto di logging strutturato Go, slog
, e per configurare OpenTelemetry.
L'esempio di codice seguente illustra una funzione main
che chiama due
funzioni helper, setupLogging()
e setupOpenTelemetry()
. Queste funzioni helper configurano il pacchetto di logging e OpenTelemetry.
Per visualizzare l'esempio completo, fai clic su more_vert Altro, quindi seleziona Visualizza su GitHub.
Dopo aver configurato il pacchetto di logging, per collegare i log ai dati di traccia, devi passare il comando Go Context
al logger. Per maggiori informazioni, consulta la sezione Scrivere log strutturati di questo documento.
Configura OpenTelemetry
Per raccogliere ed esportare tracce e metriche utilizzando il
protocollo OTLP, configura le istanze TracerProvider
e MeterProvider
globali.
Il seguente esempio di codice illustra la funzione setupOpenTelemetry
,
che viene richiamata dalla funzione main
:
L'esempio di codice precedente configura l'elemento TextMapPropagator
globale in modo da utilizzare il formato Contesto traccia W3C per propagare il contesto delle tracce. Questa configurazione garantisce che gli intervalli abbiano la
corretta relazione padre-figlio all'interno di una traccia.
Per garantire che tutti i dati di telemetria in sospeso vengano cancellati e che le connessioni vengano chiuse correttamente, la funzione setupOpenTelemetry
restituisce una funzione denominata
shutdown
, che esegue queste azioni.
Configura il logging strutturato
Per includere le informazioni di traccia come parte dei log in formato JSON scritti nell'output standard, configura il pacchetto di logging strutturato Go, slog
.
Il seguente esempio di codice illustra la funzione setupLogging
,
che viene richiamata dalla funzione main
:
Il codice precedente chiama la funzione handlerWithSpanContext
, che estrae
le informazioni dall'istanza Context
e le aggiunge come attributi
a un log. Questi attributi possono quindi essere utilizzati per correlare un log a una traccia:
logging.googleapis.com/trace
: nome risorsa della traccia associata alla voce di log.logging.googleapis.com/spanId
: l'ID intervallo con la traccia associata alla voce di log.logging.googleapis.com/trace_sampled
: il valore di questo campo deve esseretrue
ofalse
.
Per ulteriori informazioni su questi campi, consulta la struttura di LogEntry
.
Aggiungi la strumentazione al server HTTP
Per aggiungere traccia e strumentazione metrica alle richieste gestite dal server HTTP, utilizza OpenTelemetry. Nell'esempio seguente viene utilizzato il gestore otelhttp
per propagare il contesto e per la strumentazione di tracce e metriche:
Nel codice precedente, il gestore otelhttp
utilizza le istanze
TracerProvider
, MeterProvider
e TextMapPropagator
globali. La funzione setupOpenTelemetry
configura queste istanze.
Collega intervalli di tracce con log e metriche
Per collegare intervalli di server e client e associare metriche e log, passa l'istanza Go Context
alla richiesta HTTP e quando scrivi i log.
L'esempio seguente illustra un gestore di route che estrae l'istanza Go Context
e la passa al logger e alla funzione callSingle
, effettuando una richiesta HTTP in uscita:
Nel codice precedente, la chiamata di funzione r.Context()
recupera l'elemento Go Context
dalla richiesta HTTP.
Aggiungi la strumentazione al client HTTP
Per inserire il contesto della traccia nelle richieste HTTP in uscita e per aggiungere traccia e strumentazione delle metriche, chiama la funzione otelhttp.Get
.
Nell'esempio seguente, la funzione callSingle
esegue questa azione:
Nel codice precedente, il gestore otelhttp
utilizza le istanze
TracerProvider
, MeterProvider
e TextMapPropagator
globali. La funzione setupOpenTelemetry
configura queste istanze.
Scrittura di log strutturati
Per scrivere log strutturati che si collegano a una traccia, utilizza il pacchetto di logging strutturato di Go, slog
, e passa l'istanza Go Context
al logger.
L'istanza Go Context
è necessaria quando vuoi collegare un log a un intervallo.
Ad esempio, la seguente istruzione mostra come chiamare il metodo InfoContext
per slog
e come aggiungere il campo subRequests
all'istanza JSON:
slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))
Esegui un'app di esempio configurata per raccogliere dati di telemetria
L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP per metriche e tracce. Per instradare la telemetria a Google Cloud, questo esempio utilizza
l'elemento OpenTelemetry Collector
configurato con gli esportatori Google. Il generatore di carico nell'app invia richieste alle relative route.
Scarica ed esegui il deployment dell'app
Per eseguire l'esempio, segui questi passaggi:
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Clona il repository:
git clone https://github.com/GoogleCloudPlatform/golang-samples
Vai alla directory OpenTelemetry:
cd golang-samples/opentelemetry/instrumentation
Crea ed esegui l'esempio:
docker compose up --abort-on-container-exit
Se non è in esecuzione su Cloud Shell, esegui l'applicazione con la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
che punta a un file delle credenziali. Credenziali predefinite dell'applicazione fornisce un file di credenziali all'indirizzo$HOME/.config/gcloud/application_default_credentials.json
.# Set environment variables export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" export USERID="$(id -u)" # Run docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
Visualizzare le metriche
La strumentazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Metrics Explorer:
Prometheus/http_server_duration/histogram
registra la durata delle richieste del server e archivia i risultati in un istogramma.Prometheus/http_server_request_content_length_total/counter
registra la lunghezza dei contenuti della richiesta per le route HTTP/multi
e/single
. Le misurazioni di questa metrica sono cumulative, il che significa che ogni valore rappresenta il totale dall'inizio della raccolta dei valori.Prometheus/http_server_response_content_length_total/counter
registra la lunghezza del contenuto della risposta per le route HTTP/multi
e/single
. Le misurazioni di questa metrica sono cumulative.
-
Nella console Google Cloud, vai alla pagina leaderboard Esplora metriche:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- Nell'elemento Metrica, espandi il menu Seleziona una metrica,
inserisci
http_server
nella barra dei filtri e utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:- Nel menu Risorse attive, seleziona Target Prometheus.
- Nel menu Categorie di metriche attive, seleziona Http.
- Seleziona una metrica nel menu Metriche attive.
- Fai clic su Applica.
- Configura la modalità di visualizzazione dei dati.
Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, il che genera la visualizzazione del grafico nel grafico. Per ulteriori informazioni, consulta Tipi, tipi e conversioni.
Quando vengono misurati valori interi o doppi, ad esempio con le due metriche
counter
, Metrics Explorer somma automaticamente tutte le serie temporali. Per visualizzare i dati relativi alle route HTTP/multi
e/single
, imposta il primo menu della voce Aggregazione su Nessuna.Per saperne di più sulla configurazione di un grafico, consulta Selezionare le metriche quando si utilizza Esplora metriche.
Visualizza le tue tracce
Per visualizzare i dati di traccia, segui questi passaggi:
-
Nella console Google Cloud, vai alla pagina Esplora tracce.
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
- Nel grafico a dispersione, seleziona una traccia con URI
/multi
. Nel grafico di Gantt nel riquadro Dettagli traccia, seleziona l'intervallo con l'etichetta
/multi
.Si apre un riquadro che mostra informazioni sulla richiesta HTTP. Questi dettagli includono il metodo, il codice di stato, il numero di byte e lo user agent del chiamante.
Per visualizzare i log associati a questa traccia, seleziona la scheda Log ed eventi.
La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandila. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.
Per ulteriori informazioni sull'utilizzo di Explorer di Cloud Trace, consulta Trovare ed esplorare le tracce.
visualizza i log
Da Esplora log puoi esaminare i log e puoi anche visualizzare le tracce associate, se presenti.
-
Nella console Google Cloud, vai alla pagina Esplora log:
Se usi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
Individua un log con la descrizione di
handle /multi request
.Per visualizzare i dettagli del log, espandi la voce di log. Nel campo
jsonPayload
è presente una voce con l'etichettasubRequests
. Questa voce è stata aggiunta da un'istruzione nella funzionehandleMulti
.Fai clic su Tracce in una voce di log con il messaggio "handle /multi-richiesta", quindi seleziona Visualizza dettagli traccia.
Si apre un riquadro Dettagli traccia che mostra la traccia selezionata.
Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizzare i log con Esplora log.
Passaggi successivi
- OpenTelemetry
- Specifiche OTLP
- Logging strutturato
- Risoluzione dei problemi di Managed Service per Prometheus
- Risolvi i problemi di Cloud Trace