Genera tracce e metriche con Node.js

Questo documento descrive come modificare un'app JavaScript Node.js per raccogliere dati di traccia e metriche utilizzando il framework open source OpenTelemetry e come scrivere log JSON strutturati all'esterno standard. 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.

Informazioni sulla strumentazione manuale e automatica

Per questo linguaggio, OpenTelemetry definisce la strumentazione automatica come la pratica di raccogliere dati di telemetria da librerie e framework senza apportare modifiche al codice. Tuttavia, devi installare moduli e impostare le variabili di ambiente.

Questo documento non descrive la strumentazione automatica. Per informazioni su questo argomento, consulta Strumentazione automatica per nodo.

Per informazioni generali, consulta OpenTelemetry Instrumentation for Node.

Prima di iniziare

Abilita le API Cloud Logging, Cloud Monitoring, and Cloud Trace.

Abilita le API

Instrumenta la tua app per raccogliere tracce, metriche e log

Per consentire alla tua app di raccogliere dati di traccia e metriche e di scrivere JSON strutturato all'out standard, segui i passaggi descritti nelle sezioni successive di questo documento:

  1. Configura OpenTelemetry
  2. Configura la tua app per precaricare la configurazione OpenTelemetry
  3. Configurare il logging strutturato
  4. Scrivere log strutturati

Configura OpenTelemetry

La configurazione predefinita per l'SDK OpenTelemetry Node.js esporta le tracce utilizzando il protocollo OTLP. Inoltre, configura OpenTelemetry per l'utilizzo del formato W3C Trace Context per la propagazione del contesto della traccia. Questa configurazione garantisce che gli intervalli abbiano la relazione padre-figlio corretta all'interno di una traccia.

Il seguente esempio di codice mostra un modulo JavaScript per configurare OpenTelemetry.

Per visualizzare l'esempio completo, fai clic su Altro, quindi seleziona Visualizza su GitHub.


diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.getEnv().OTEL_LOG_LEVEL
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});

Il precedente esempio di codice configura OpenTelemetry per l'esportazione delle metriche tramite il protocollo OTLP e il pacchetto @opentelemetry/auto-instrumentations-node per configurare tutte le strumentazioni Node.js disponibili.

Per garantire che tutti i dati di telemetria in attesa vengano cancellati e che le connessioni vengano chiuse senza dovere prima dell'arresto dell'applicazione, il gestore SIGTERM chiama shutdown.

Per ulteriori informazioni e opzioni di configurazione, consulta la pagina sulla strumentazione automatica di Node.js di OpenTelemetry.

Configura la tua app per precaricare la configurazione OpenTelemetry

Per configurare l'app per scrivere log strutturati e raccogliere metriche e dati di traccia utilizzando OpenTelemetry, aggiorna la chiamata dell'app per precaricare il modulo di strumentazione con il flag --require 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 Node.js di OpenTelemetry.

Il seguente esempio di codice illustra un Dockerfile che passa il flag --require:

CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

Configura il logging strutturato

Per includere le informazioni di traccia nei log in formato JSON scritti nell'output standard, configura l'app in modo che restituisca log strutturati in formato JSON. Fastify utilizza il framework dei log Pin e fornisce un logger in ogni gestore delle richieste. Il seguente esempio di codice illustra un oggetto LoggerOptions Pino che configura l'app per l'output di log strutturati JSON:


// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;

La configurazione precedente estrae le informazioni sull'intervallo attivo dal messaggio di log, quindi le aggiunge come attributi al log strutturato JSON. 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 essere true o false.

Per maggiori informazioni su questi campi, consulta la struttura LogEntry.

Per utilizzare la configurazione Pino con Fastify, passa l'oggetto di configurazione logger durante la creazione dell'app Fastify:

// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

Scrittura di log strutturati

Per scrivere log strutturati che rimandino a una traccia, utilizza il logger Pino fornito da Fastify. Ad esempio, la seguente istruzione mostra come chiamare il metodo Logger.info():

request.log.info({subRequests}, 'handle /multi request');

OpenTelemetry compila automaticamente le voci di log Pino con il contesto dell'intervallo dell'intervallo attivo corrente nel contesto di OpenTelemetry. Questo contesto di intervallo viene quindi incluso nei log JSON come descritto in Configurare il logging strutturato.

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 metriche e tracce e il framework Fastify. Per instradare la telemetria a Google Cloud, in questo esempio viene utilizzato il valore Collector di OpenTelemetry configurato con gli esportatori Google. L'app ha due endpoint:

  • L'endpoint /multi è gestito dalla funzione handleMulti. 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.

    /**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the handler body.
 */
fastify.get('/multi', async request => {
  const subRequests = randInt(3, 8);
  request.log.info({subRequests}, 'handle /multi request');

  for (let i = 0; i < subRequests; i++) {
    await axios.get(`http://localhost:${port}/single`);
  }
  return 'ok';
});

  • L'endpoint /single è gestito dalla funzione handleSingle. Quando questo endpoint riceve una richiesta, si blocca per un breve ritardo e risponde con una stringa.

    /**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 */
fastify.get('/single', async request => {
  // Sleep between 100-200 milliseconds
  const sleepMillis = randInt(100, 200);
  request.log.info({sleepMillis}, 'Going to sleep');
  await sleep(sleepMillis);
  return `slept ${sleepMillis}\n`;
});

Scaricare e implementare l'app

Per eseguire l'esempio:

  1. Nella console Google Cloud, attiva Cloud Shell.

    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.

  2. Clona il repository:

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js

  3. Vai alla directory di esempio:

    cd opentelemetry-operations-js/samples/instrumentation-quickstart

  4. 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. Application default Credentials (Credenziali predefinite dell'applicazione) fornisce un file delle 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_milliseconds/histogram registra la durata delle richieste del server e archivia i risultati in un istogramma.

  • Prometheus/http_client_duration_milliseconds/histogram registra la durata delle richieste del client e archivia i risultati in un istogramma.

Per visualizzare le metriche generate dall'app di esempio:

  1. Nella console Google Cloud, vai alla pagina Metrics Explorer :

    Vai a Metrics Explorer

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Monitoring.

  2. Nell'elemento Metrica, espandi il menu Seleziona una metrica, inserisci http_server nella barra dei filtri, poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
    1. Nel menu Risorse attive, seleziona Target Prometheus.
    2. Nel menu Categorie di metriche attive, seleziona Http.
    3. Nel menu Metriche attive, seleziona una metrica.
    4. Fai clic su Applica.
  3. Configura il modo in cui vengono visualizzati i dati.

    Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, mostrando una frequenza 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 per le route HTTP /multi e /single, imposta il primo menu della voce Aggregation su None.

    Per maggiori informazioni sulla configurazione di un grafico, consulta Selezionare le metriche quando si utilizza Metrics Explorer.

Visualizza le tue tracce

Per visualizzare i dati di traccia:

  1. Nella console Google Cloud, vai alla pagina Esplora traccia:

    Vai a Trace Explorer

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nel grafico a dispersione, seleziona una traccia con l'URI di /multi.

  3. Nel grafico di Gantt nel riquadro Dettagli traccia, seleziona l'intervallo denominato /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.

  4. 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, espandi la voce di log. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

Per maggiori informazioni sull'utilizzo di Cloud Trace Explorer, consulta Trovare ed esplorare tracce.

visualizza i log

In Esplora log puoi esaminare i log e visualizzare le tracce associate, se presenti.

  1. Nella console Google Cloud, vai alla pagina Esplora log:

    Vai a Esplora log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Logging.

  2. Individua un log con la descrizione di handle /multi request.

    Per visualizzare i dettagli del log, espandi la voce di log.

  3. Fai clic su Tracce su una voce di log con il messaggio "handle /richiesta multipla", quindi seleziona Visualizza dettagli traccia.

    Si apre il 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