Quando utilizzi un collettore OpenTelemetry, strumenta l'applicazione con l'SDK e l'esportatore in-process OTLP dell'SDK. Questa strumentazione è neutrale rispetto al fornitore. Devi anche implementare un raccoglitore OpenTelemetry che riceve la telemetria dall'esportatore in-process e poi la esporta nel tuo Google Cloud progetto. Per scoprire di più sui raccoglitori, consulta Raccoglitore OpenTelemetry creato da Google.
Ti consigliamo di utilizzare un raccoglitore OpenTelemetry per esportare i dati di telemetria quando l'ambiente supporta l'utilizzo del raccoglitore. Per alcuni ambienti, devi utilizzare un esportatore in-process che invia direttamente i dati al tuo progettoGoogle Cloud . Per informazioni sull'instrumentazione in-process, consulta Migrazione dall'esportatore di Trace all'endpoint OTLP.
Per saperne di più sull'instrumentazione, consulta i seguenti documenti:
Informazioni sul contesto
Il contesto di OpenTelemetry è un meccanismo per trasferire valori con ambito di esecuzione tra le API all'interno di un processo. Un utilizzo importante del contesto è quello di trasportare l'intervallo attivo corrente in modo che possa essere modificato o a cui si possa fare riferimento come elemento principale di eventuali nuovi intervalli quando vengono creati. In sintesi:
Contesto si riferisce al meccanismo per propagare i valori con ambito di esecuzione, inclusa l'attuale estensione attiva, tra le API all'interno di un processo.
Span Context è un oggetto immutabile in ogni span che include l'ID traccia, l'ID span, i flag e lo stato della traccia.
La propagazione è il meccanismo che sposta il contesto tra servizi e processi.
context.Context della libreria standard di Go trasporta anche valori
con ambito tra i limiti delle API. In genere, le funzioni del 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 come implementazione del contesto OpenTelemetry in Go.
Prima di iniziare
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
-
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Crea o seleziona un Google Cloud progetto.
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto
(
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Creare un progetto Google Cloud :
gcloud projects create PROJECT_ID
Sostituisci
PROJECT_IDcon un nome per il progetto Google Cloud che stai creando. -
Seleziona il progetto Google Cloud che hai creato:
gcloud config set project PROJECT_ID
Sostituisci
PROJECT_IDcon il nome del progetto Google Cloud .
-
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .
Abilita le API Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (
roles/serviceusage.serviceUsageAdmin), che include l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.gcloud services enable logging.googleapis.com
monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com -
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Crea o seleziona un Google Cloud progetto.
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto
(
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Creare un progetto Google Cloud :
gcloud projects create PROJECT_ID
Sostituisci
PROJECT_IDcon un nome per il progetto Google Cloud che stai creando. -
Seleziona il progetto Google Cloud che hai creato:
gcloud config set project PROJECT_ID
Sostituisci
PROJECT_IDcon il nome del progetto Google Cloud .
-
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .
Abilita le API Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (
roles/serviceusage.serviceUsageAdmin), che include l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.gcloud services enable logging.googleapis.com
monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com Se esegui l'esempio 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 all'applicazione 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) -
Cloud Telemetry Traces Writer (
roles/telemetry.tracesWriter)
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.
-
Logs Writer (
Instrumenta la tua app per raccogliere tracce, metriche e log
Per instrumentare l'app in modo da raccogliere dati di traccia e metriche e scrivere JSON strutturato in standard out, segui i passaggi descritti nelle sezioni successive di questo documento:
- Configurare la funzione principale
- Configura OpenTelemetry
- Configura il logging strutturato
- Aggiungere la strumentazione al server HTTP
- Collegare gli intervalli di traccia con log e metriche
- Aggiungere la strumentazione al client HTTP
- Scrivere log strutturati
Configura la funzione principale
Per configurare l'app in modo che scriva log strutturati e raccolga metriche e
dati di traccia utilizzando OpenTelemetry, aggiorna la funzione main per
configurare il pacchetto di logging strutturato Go, slog, e OpenTelemetry.
Il seguente esempio di codice 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 e poi seleziona Visualizza su GitHub.
Dopo aver configurato il pacchetto di logging, per collegare i log ai dati di traccia, devi passare Context al logger. Per saperne di più, consulta la sezione Scrivere log strutturati di questo documento.
Configurare OpenTelemetry
Per raccogliere ed esportare tracce e metriche utilizzando il
protocollo OTLP, configura le istanze globali TracerProvider
e MeterProvider.
Il seguente esempio di codice illustra la funzione setupOpenTelemetry,
chiamata dalla funzione main:
L'esempio di codice precedente configura TextMapPropagator globale in modo che utilizzi il formato
W3C Trace Context per la propagazione del contesto
di traccia. Questa configurazione garantisce che gli span abbiano la
corretta relazione padre-figlio all'interno di una traccia.
Per assicurarsi che tutti i dati di telemetria in attesa vengano svuotati e che le connessioni vengano chiuse
in modo controllato, la funzione setupOpenTelemetry restituisce una funzione denominata
shutdown, che esegue queste azioni.
Configura il logging strutturato
Per includere le informazioni di tracciamento nei 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,
chiamata 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 essere utilizzati per correlare un log a una traccia:
logging.googleapis.com/trace: il nome della 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 esseretrueofalse.
Per saperne di più su questi campi, consulta la struttura LogEntry.
Aggiungi la strumentazione al server HTTP
Per aggiungere l'instrumentazione di tracce e metriche alle richieste gestite dal server HTTP, utilizza OpenTelemetry. L'esempio seguente utilizza il gestore otelhttp
per propagare il contesto e per la strumentazione di traccia e metrica:
Nel codice precedente, il gestore otelhttp utilizza le istanze globali
TracerProvider, MeterProvider e TextMapPropagator. La
funzione setupOpenTelemetry configura queste istanze.
Collegare gli intervalli di traccia con log e metriche
Per collegare gli span del server e del client e per associare metriche e log, passa l'istanza Context di Go 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, che effettua una richiesta HTTP in uscita:
Nel codice precedente, la chiamata di funzione r.Context() recupera il valore Context di Go
dalla richiesta HTTP.
Aggiungere la strumentazione al client HTTP
Per inserire il contesto di traccia nelle richieste HTTP in uscita e per aggiungere
l'instrumentazione di traccia e metrica, chiama la funzione otelhttp.Get.
Nell'esempio riportato di seguito, la funzione callSingle esegue questa azione:
Nel codice precedente, il gestore otelhttp utilizza le istanze globali
TracerProvider, MeterProvider e TextMapPropagator. La
funzione setupOpenTelemetry configura queste istanze.
Scrittura di log strutturati
Per scrivere log strutturati che rimandano a una traccia, utilizza il pacchetto di logging strutturato di Go, slog, e passa l'istanza Context di Go 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 illustra 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
La strumentazione nell'app di esempio utilizza formati indipendenti dal fornitore, come JSON
per i dati di log e OTLP per i dati di metrica e traccia. Collector OpenTelemetry invia
dati di log e metriche al tuo progetto utilizzando gli esportatori Google. Invia i dati di traccia al tuo progetto utilizzando l'API Telemetry, che utilizza OTLP.
Il generatore di carico nell'app invia richieste alle route dell'app.
Scaricare ed eseguire il deployment dell'app
Per eseguire l'esempio:
-
Nella console Google Cloud , attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.
Clona il repository:
git clone https://github.com/GoogleCloudPlatform/golang-samplesVai alla directory OpenTelemetry:
cd golang-samples/opentelemetry/instrumentationCrea ed esegui l'esempio:
docker compose up --abort-on-container-exitSe non esegui l'applicazione su Cloud Shell, esegui l'applicazione con la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALSche punta a un file delle credenziali. Credenziali predefinite dell'applicazione fornisce un file di credenziali in$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
L'instrumentazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Esplora metriche:
Prometheus/http_server_duration_milliseconds/histogramregistra la durata delle richieste del server e memorizza i risultati in un istogramma.Prometheus/http_client_duration_milliseconds/histogramregistra la durata delle richieste client e memorizza i risultati in un istogramma.Prometheus/http_server_response_size_bytes_total/counterregistra la lunghezza delle dimensioni della risposta per le route HTTP/multie/single. Le misurazioni per questa metrica sono cumulative, il che significa che ogni valore rappresenta il totale dall'inizio della raccolta dei valori.
-
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.
- Nella barra degli strumenti della console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
- Nell'elemento Metrica, espandi il menu Seleziona una metrica,
digita
http_servernella barra dei filtri e poi 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.
- Nel menu Metriche attive, seleziona una metrica.
- Fai clic su Applica.
Per aggiungere filtri, che rimuovono le serie temporali dai risultati della query, utilizza l'elemento Filtro.
- 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 comporta la visualizzazione di una frequenza nel grafico. Per maggiori 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 per le route HTTP/multie/single, imposta il primo menu della voce Aggregazione su Nessuna.Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche durante l'utilizzo di Esplora metriche.
Visualizza le tracce
Potrebbero essere necessari diversi minuti prima che i dati di tracciamento siano disponibili. Ad esempio, quando i dati di traccia vengono ricevuti dal tuo progetto, Google Cloud Observability potrebbe dover creare un database per archiviarli. La creazione del database può richiedere alcuni minuti e durante questo periodo non sono disponibili dati di traccia da visualizzare.
Per visualizzare i dati di traccia:
-
Nella console Google Cloud , vai alla pagina
Esplora tracce:
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
- Nella sezione della tabella della pagina, seleziona una riga con il nome dello span
/multi. Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona l'intervallo etichettato
/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 Esplora tracce, consulta Trovare ed esplorare le tracce.
Visualizza i log
Da Esplora log puoi esaminare i log e visualizzare le tracce associate, se esistenti.
-
Nella console Google Cloud , vai alla pagina Esplora log:
Se utilizzi 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 etichettatasubRequests. Questa voce è stata aggiunta da un'istruzione nella funzionehandleMulti.Fai clic su
Trace in una voce di log con il messaggio
"handle /multi request", quindi seleziona Visualizza dettagli trace.Si apre un riquadro Dettagli su Trace che mostra la traccia selezionata.
I dati di log potrebbero essere disponibili diversi minuti prima dei dati di traccia. Se si verifica un errore durante la visualizzazione dei dati di traccia cercando una traccia per ID o seguendo i passaggi descritti in questa attività, attendi un minuto o due e riprova.
Per ulteriori informazioni sull'utilizzo di Esplora log, vedi Visualizza i log utilizzando Esplora log.
Passaggi successivi
- OpenTelemetry
- Specifica OTLP
- Logging strutturato
- Risoluzione dei problemi di Managed Service per Prometheus
- Risoluzione dei problemi di Cloud Trace