Questa pagina è stata tradotta dall'API Cloud Translation.

Esempio di ispezione 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 nell'output 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.

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

Informazioni sulla strumentazione manuale e senza codice

Per questo linguaggio, OpenTelemetry definisce la strumentazione zero-code come la pratica di raccolta della telemetria da librerie e framework senza apportare modifiche al codice. Tuttavia, devi installare i moduli e impostare le variabili di ambiente.

Questo documento non descrive l'instrumentazione senza codice. Per informazioni su questo argomento, consulta Strumentazione zero-code JavaScript.

Per informazioni generali, vedi OpenTelemetry Instrumentation for Node.

Prima di iniziare

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

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 OpenTelemetry
Configurare l'app per precaricare la configurazione di OpenTelemetry
Configurare il logging strutturato
Scrivere log strutturati

Configura OpenTelemetry

La configurazione predefinita dell'SDK OpenTelemetry Node.js esporta le tracce utilizzando il protocollo OTLP. Configura inoltre OpenTelemetry per utilizzare il formato W3C Trace Context per la propagazione del contesto di traccia. 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'esempio completo, fai clic su Altro e poi 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 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 strumentazioni Node.js disponibili.

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

Per ulteriori informazioni e opzioni di configurazione, consulta Configurazione dell'instrumentazione zero-code.

Configurare l'app per precaricare la configurazione di OpenTelemetry

Per configurare l'app in modo che scriva log strutturati e raccolga metriche e dati di traccia utilizzando OpenTelemetry, aggiorna la chiamata 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 saperne di più, consulta la pagina Guida introduttiva a OpenTelemetry Node.js.

Il seguente esempio di codice mostra 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 tracciamento 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 di logging Pino e fornisce un logger in ogni gestore delle richieste. Il seguente esempio di codice mostra un oggetto Pino LoggerOptions che configura l'app per generare log strutturati in formato 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 sullo span attivo dal messaggio di log e le aggiunge come attributi al log strutturato JSON. 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 essere true o false.

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

Per utilizzare la configurazione Pino con Fastify, passa l'oggetto di configurazione del 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 rimandano 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 dello span dello span attivo corrente nel contesto OpenTelemetry. Questo contesto dello span viene poi incluso nei log JSON come descritto in Configurare la registrazione strutturata.

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 la telemetria a Google Cloud, questo esempio utilizza Collector OpenTelemetry configurato con gli esportatori Google. L'app ha due endpoint:

L'endpoint /multi viene 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 viene gestito dalla funzione handleSingle. Quando questo endpoint riceve una richiesta, rimane inattivo per un breve periodo 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`;
});

Scaricare ed eseguire il deployment dell'app

Per eseguire l'esempio:

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.

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 campione:

docker compose up --abort-on-container-exit

Se non esegui l'applicazione 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 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/histogram registra la durata delle richieste del server e memorizza i risultati in un istogramma.
Prometheus/http_client_duration_milliseconds/histogram registra la durata delle richieste client e memorizza i risultati in un istogramma.

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 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_server nella barra dei filtri e poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
1. Nel menu Risorse attive, seleziona Destinazione Prometheus.
2. Nel menu Categorie di metriche attive, seleziona Http.
3. Nel menu Metriche attive, seleziona una metrica.
4. 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 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 /multi e /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.

Visualizzare 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 Google Cloud console, vai alla pagina Esplora tracce:
Vai a Trace Explorer

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 Google Cloud console, 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.
Individua un log con la descrizione di 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", quindi seleziona Visualizza dettagli traccia.

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 saperne di più sull'utilizzo di Esplora log, consulta Visualizzare i log utilizzando Esplora log.