Genera tracce e metriche con Node.js

Questo documento descrive come modificare un'app JavaScript Node.js per raccogliere tracce e metriche utilizzando il framework open source OpenTelemetry, e come per scrivere log JSON strutturati in uscita standard. Il presente documento fornisce inoltre informazioni su un'app Node.js di esempio che puoi installare ed eseguire. L'app utilizza il framework web Fastify ed è configurato per generare metriche, per le tracce e i log.

Per saperne di più sulla strumentazione, consulta i seguenti documenti:

• Strumentazione e osservabilità.
• Scegli un approccio alla strumentazione.

Informazioni sulla strumentazione manuale e automatica

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

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

Per informazioni generali, vedi OpenTelemetry Instrumentation per nodo.

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 instrumentare l'app in modo che raccolga dati relativi a tracce e metriche e per scrivere da JSON strutturato a Standard Out, esegui i seguenti passaggi come descritto nelle sezioni successive del presente documento:

1. Configurare 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 protocollo W3C Formato del contesto traccia per la propagazione della traccia contesto. Questa configurazione garantisce che gli intervalli abbiano la corretta relazione padre-figlio all'interno di una traccia.

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

Per visualizzare l'anteprima completa, 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));
});

L'esempio di codice precedente configura OpenTelemetry per esportare le metriche utilizzando OTLP e utilizza @opentelemetry/auto-instrumentations-node per configurare tutte la strumentazione Node.js disponibile.

Per garantire che tutti i dati di telemetria in sospeso siano stati eliminati e che le connessioni siano chiuse controllato prima dell'arresto dell'applicazione, il gestore SIGTERM chiama shutdown.

Per ulteriori informazioni e opzioni di configurazione, vedi OpenTelemetry Node.js automatico dei dati.

Configura la tua app per precaricare la configurazione OpenTelemetry

Configurare l'app per la scrittura di log strutturati e la raccolta di metriche e tracce di dati utilizzando OpenTelemetry, aggiorna la chiamata dell'app per precaricare di strumentazione con il flag --require di Node.js. Utilizzo Il flag --require assicura che OpenTelemetry venga inizializzato prima della tua app . Per ulteriori informazioni, consulta la pagina relativa al recupero di OpenTelemetry Node.js Iniziata.

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 all'interno dei log in formato JSON scritti in standard, configura la tua app per generare log strutturati in formato JSON. Fastify utilizza il framework di log Pino e fornisce un logger in ogni come gestore delle richieste. Il seguente esempio di codice illustra un LoggerOptions Pino che configura l'app per generare 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 aggiunge queste informazioni come attributi al file JSON strutturato log. Questi attributi possono quindi essere utilizzati per correlare un log a una traccia:

• logging.googleapis.com/trace: nome risorsa della traccia associata a la voce di log.
• logging.googleapis.com/spanId: l'ID intervallo con la traccia che è associati alla voce di log.
• logging.googleapis.com/trace_sampled: il valore di questo campo deve essere true o false.

Per saperne di più su questi campi, consulta la LogEntry alla struttura del centro di costo.

Per utilizzare la configurazione Pino con Fastify, passa l'oggetto di configurazione logger quando creando l'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 si colleghino a una traccia, utilizza il metodo Pino fornito da Fastify logger. 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 parametro span contesto dell'intervallo attivo corrente in OpenTelemetry Contesto. Questo contesto di intervallo viene quindi incluso nei log JSON descritti in Configura il logging strutturato.

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

• L'endpoint /multi è gestito dalla funzione handleMulti. Il carico nell'app invia richieste all'endpoint /multi. Quando questo quando un endpoint riceve una richiesta, invia da 3 a 7 l'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, dorme per un breve ritardo e poi 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`;
  });

Scarica ed esegui il deployment dell'app

Nota: consigliamo di eseguire l'app di esempio utilizzando Cloud Shell. Tuttavia, se vuoi eseguire l'app di esempio in locale su Linux o Mac, salta il primo segui le istruzioni riportate di seguito.

Per eseguire l'esempio, segui questi passaggi:

1. In the Google Cloud console, activate Cloud Shell.

   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.

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 stai utilizzando Cloud Shell, esegui l'applicazione con GOOGLE_APPLICATION_CREDENTIALS variabile di ambiente che punta a una delle credenziali. App predefinita Credenziali 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 Prometheus che puoi visualizzare utilizzando Esplora metriche:

• 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: procedi nel seguente modo:

1. Nella console Google Cloud, vai alla Pagina Esplora metriche:

   Vai a Esplora metriche

   Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoraggio.

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. Seleziona una metrica nel menu Metriche attive.
   4. Fai clic su Applica.
3. Configura la modalità di visualizzazione dei dati.
   

   Quando le misurazioni di una metrica sono cumulativo, Metrics Explorer normalizza automaticamente i dati misurati il periodo di allineamento, che determina la visualizzazione di un tasso nel grafico. Per per saperne di più, consulta Tipi, tipi e conversioni.

   Quando vengono misurati valori interi o doppi, ad esempio con i due valori 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 Aggregation su None.

   Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche quando utilizzi Esplora metriche.

Visualizza le tue tracce

Per visualizzare i dati di traccia, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Esplora tracce.

   Vai a Trace Explorer

   Puoi trovare questa pagina anche utilizzando la barra di ricerca.

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

3. Nel grafico di Gantt, all'interno del riquadro Dettagli traccia, seleziona l'intervallo con l'etichetta /multi.

   Si apre un riquadro che mostra informazioni sulla richiesta HTTP. Questi tra cui metodo, codice di stato, numero di byte e e lo user agent del chiamante.

4. Per visualizzare i log associati a questa traccia, seleziona Log e Eventi.

   La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandere la voce di log. Puoi anche fare clic su Visualizza log e visualizzare il log. mediante Esplora log.

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

Visualizza i log

In Esplora log puoi esaminare i log e anche 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 con il 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 in una voce di log con "handle /multirichiesta" quindi seleziona Visualizza dettagli traccia.

   Si apre un riquadro Dettagli traccia che mostra la traccia selezionata.

Per ulteriori informazioni sull'uso 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
• Risolvi i problemi di Cloud Trace