Questo documento descrive come modificare un'app JavaScript Node.js per raccogliere dati su tracce e metriche utilizzando il framework open source OpenTelemetry e come scrivere log JSON strutturati nello standard out. Questo documento fornisce anche informazioni su un'app Node.js di esempio che puoi installare ed eseguire. L'app utilizza il framework web Fastify ed è configurata per generare metriche, tracce e log.
Per scoprire di più sull'instrumentazione, consulta i seguenti documenti:
Informazioni sulla misurazione manuale e automatica
Per questo linguaggio, OpenTelemetry definisce la strumentazione automatica come la pratica di raccogliere la telemetria da librerie e framework senza apportare modifiche al codice. Tuttavia, puoi installare i moduli e impostare le variabili di ambiente.
Questo documento non descrive la misurazione automatica. Per informazioni su questo argomento, consulta Strumentazione automatica per Node.
Per informazioni generali, consulta OpenTelemetry Instrumentation for Node.
Prima di iniziare
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Instrumenta l'app per raccogliere tracce, metriche e log
Per eseguire l'instrumentazione dell'app in modo da raccogliere dati sulle metriche e sulle tracce e scrivere JSON strutturato nello standard output, svolgi i seguenti passaggi come descritto nelle sezioni successive di questo documento:
- Configurare OpenTelemetry
- Configurare l'app per precaricare la configurazione di OpenTelemetry
- Configurare il logging strutturato
- Scrivere log strutturati
Configurare OpenTelemetry
La configurazione predefinita per l'SDK Node.js di OpenTelemetry esporta le tracce utilizzando il protocollo OTLP. Inoltre, configura OpenTelemetry in modo da utilizzare il formato W3C Trace Context per propagare il contesto traccia. Questa configurazione garantisce che gli intervalli abbiano la relazione padre-figlio corretta all'interno di una traccia.
Il seguente esempio di codice illustra un modulo JavaScript per configurare OpenTelemetry.
Per visualizzare l'esempio completo, fai clic su more_vert Altro e poi seleziona Visualizza su GitHub.
Il esempio di codice precedente configura OpenTelemetry per esportare le metriche utilizzando il protocollo OTLP e utilizza il pacchetto @opentelemetry/auto-instrumentations-node
per configurare tutte le misurazioni di Node.js disponibili.
Per garantire che tutta la telemetria in attesa venga svuotata e che le connessioni vengano chiuse in modo corretto prima dell'arresto dell'applicazione, il gestore SIGTERM
chiama shutdown
.
Per ulteriori informazioni e opzioni di configurazione, consulta la strumentazione automatica di OpenTelemetry Node.js.
Configurare l'app per precaricare la configurazione di OpenTelemetry
Per configurare l'app in modo che scriva log strutturati e raccolga metriche e dati traccia utilizzando OpenTelemetry, aggiorna l'invocazione dell'app per precaricare il modulo di strumentazione con il flag --require
di Node.js. L'utilizzo del flag --require
garantisce che OpenTelemetry venga inizializzato prima dell'avvio dell'app. Per ulteriori informazioni, consulta la guida introduttiva a OpenTelemetry Node.js.
Il seguente esempio di codice illustra un Dockerfile che passa il flag --require
:
Configurare il logging strutturato
Per includere le informazioni sulla traccia all'interno dei log in formato JSON scritti nell'output standard, configura l'app in modo da generare log strutturati in formato JSON.
Fastify utilizza il framework di log Pino e fornisce un logger in ogni gestore delle richieste. Il seguente esempio di codice illustra un oggetto Pino LoggerOptions
che configura l'app in modo da generare log strutturati JSON:
La configurazione precedente estrae le informazioni sull'intervallo attivo dal messaggio del log e le aggiunge come attributi al log strutturato JSON. Questi attributi possono essere utilizzati per correlare un log con una traccia:
logging.googleapis.com/trace
: 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 esseretrue
ofalse
.
Per ulteriori informazioni su questi campi, consulta la struttura LogEntry
.
Per utilizzare la configurazione di Pino con Fastify, passa l'oggetto di configurazione del logger quando crei l'app Fastify:
Scrittura di log strutturati
Per scrivere log strutturati che rimandano a una traccia, utilizza il logger Pino fornito da Fastify. Ad esempio, l'istruzione seguente mostra come chiamare il metodo Logger.info()
:
request.log.info({subRequests}, 'handle /multi request');
OpenTelemetry compila automaticamente le voci di log di Pino con il contesto dell'ambito dell'ambito attivo corrente nel contesto OpenTelemetry. Questo contesto dell'ambito viene poi incluso nei log JSON come descritto in Configurare la registrazione strutturata.
Esegui un'app di esempio configurata per raccogliere la telemetria
L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP per le metriche e le tracce, nonché il framework Fastify. Per instradare la telemetria su Google Cloud, questo esempio utilizza Collector
OpenTelemetry configurato con gli esportatori Google. L'app ha due endpoint:
L'endpoint
/multi
è gestito dalla funzionehandleMulti
. Il generatore di carico nell'app invia richieste all'endpoint/multi
. Quando questo endpoint riceve una richiesta, invia da tre a sette richieste all'endpoint/single
sul server locale.L'endpoint
/single
è gestito dalla funzionehandleSingle
. Quando questo endpoint riceve una richiesta, entra in modalità di sospensione per un breve periodo di tempo e poi risponde con una stringa.
Scarica ed esegui il deployment dell'app
Per eseguire il sample:
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Clona il repository:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js
Vai alla directory di esempio:
cd opentelemetry-operations-js/samples/instrumentation-quickstart
Crea ed esegui il sample:
docker compose up --abort-on-container-exit
Se non esegui l'applicazione su Cloud Shell, eseguila con la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
che rimanda a un file delle credenziali. Credenziali predefinite dell'applicazione fornisce un file delle 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
La misurazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Metrics Explorer:
Prometheus/http_server_duration_milliseconds/histogram
registra la durata delle richieste al server e memorizza i risultati in un istogramma.Prometheus/http_client_duration_milliseconds/histogram
registra la durata delle richieste del client e memorizza i risultati in un istogramma.
-
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,
digita
http_server
nella barra dei filtri e poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:- Nel menu Risorse attive, seleziona Destinazione Prometheus.
- Nel menu Categorie di metriche attive, seleziona Http.
- Nel menu Metriche attive, seleziona una metrica.
- Fai clic su Applica.
- Configura la visualizzazione dei dati.
Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, in modo che il grafico mostri una percentuale. Per maggiori informazioni, consulta Tipi, generi e conversioni.
Quando vengono misurati valori interi o doppi, ad esempio con le due
counter
metriche, Metrics Explorer somma automaticamente tutte le serie temporali. Per visualizzare i dati per le route HTTP/multi
e/single
, imposta il primo menu della voce Aggregazione su Nessuna.Per ulteriori informazioni sulla configurazione di un grafico, consulta Selezionare le metriche durante l'utilizzo di Metrics Explorer.
Visualizzare le tracce
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.
- Nel grafico a dispersione, seleziona una traccia con l'URI
/multi
. Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona l'intervallo contrassegnato come
/multi
.Viene visualizzato un riquadro che mostra le informazioni sulla richiesta HTTP. Questi dettagli includono il metodo, il codice di stato, il numero di byte e l'agente utente 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 di Cloud, consulta Trovare ed esplorare le tracce.
Visualizza i log
In Esplora log puoi ispezionare i log e anche visualizzare le tracce associate, se esistono.
-
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
handle /multi request
.Per visualizzare i dettagli del log, espandi la voce di log.
Fai clic su Tracce in una voce di log con il messaggio "handle /multi request" e poi seleziona Visualizza dettagli traccia.
Viene visualizzato un riquadro Dettagli su Trace che mostra la traccia selezionata.
Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizza i log utilizzando Esplora log.
Passaggi successivi
- OpenTelemetry
- Specifiche OTLP
- Logging strutturato
- Risoluzione dei problemi di Managed Service per Prometheus
- Risolvere i problemi di Cloud Trace