Node.js e OpenTelemetry

Questa pagina è rivolta agli sviluppatori di applicazioni che vogliono raccogliere dati di Cloud Trace per applicazioni Node.js utilizzando OpenTelemetry. OpenTelemetry è un framework di strumentazione indipendente dal fornitore che puoi utilizzare per raccogliere dati di tracce e metriche. Per informazioni sulla strumentazione del codice, consulta Strumentazione e osservabilità.

Nota: le informazioni in questa pagina si limitano alla raccolta dei dati di traccia. Per un esempio più completo, uno che illustra come raccogliere dati di traccia e metriche utilizzando OpenTelemetry e come scrivere log JSON strutturati per standardizzare, consulta Generare tracce e metriche con Node.js.

Questa pagina ti guida nei seguenti passaggi:

• Installa i pacchetti OpenTelemetry.
• Configura la tua applicazione per esportare intervalli in Cloud Trace.
• Configura la tua piattaforma.

Per informazioni sulla release, consulta quanto segue:

• Ultima versione della libreria per Node.js

• Ultima release dell'esportatore di Cloud Trace per Node.js

Per i contenuti di riferimento di OpenTelemetry, consulta quanto segue:

• Tracer
• Span

Per i dettagli più recenti su OpenTelemetry per Node.js, oltre a documentazione aggiuntiva ed esempi, consulta OpenTelemetry.

Prima di iniziare

Attiva l'API richiesta.

Abilita l'API

Installazione, inizializzazione e utilizzo del client

OpenTelemetry offre i seguenti modi per instrumentare la tua applicazione:

• Strumentazione automatica per le applicazioni Node.js

  Quando utilizzi questo approccio, configuri la tua applicazione in modo da includere l'SDK @opentelemetry/sdk-trace-node. Tuttavia, non devi apportare modifiche al codice delle librerie che stai utilizzando.

• Tracciamento manuale

  Quando utilizzi questo approccio, modifichi le librerie che stai utilizzando per raccogliere le informazioni di traccia.

Le sezioni seguenti mostrano il caso d'uso per ogni strumentazione.

Strumentazione automatica

Il modulo @opentelemetry/sdk-trace-node fornisce la strumentazione automatica per le applicazioni Node.js.

La strumentazione automatica identifica automaticamente i seguenti elementi all'interno dell'applicazione:

• Framework come Express
• Protocolli comuni, come HTTP, HTTPS e gRPC
• Database come MySQL, MongoDB, Redis e PostgreSQL
• Altre librerie all'interno dell'applicazione

La strumentazione automatica fornisce tracciamento pronto all'uso, in modo da non dover apportare modifiche di codice a nessuna delle librerie che stai utilizzando. Il codice di strumentazione esegue automaticamente le seguenti azioni:

• Estrae un identificatore di contesto della traccia dalle richieste in entrata per consentire il tracciamento distribuito, se applicabile.
• Garantisce che il contesto di traccia corrente venga propagato mentre la transazione attraversa un'applicazione.
• Aggiunge l'identificatore di contesto della traccia alle richieste in uscita, consentendo alla traccia distribuita di continuare all'hop successivo, se applicabile.
• Crea e termina gli intervalli.

Il modulo utilizza plug-in per instrumentare automaticamente la tua applicazione al fine di produrre span e fornire il tracciamento end-to-end con poche righe di codice.

Strumentazione manuale

Il modulo di tracciamento manuale, @opentelemetry/sdk-trace-base, offre il controllo completo sulla creazione della strumentazione e degli intervalli. Non viene caricato async_hooks. Non utilizza l'archiviazione locale di continuazione o qualsiasi plug-in di strumentazione per impostazione predefinita. Il tracciamento manuale ha un overhead delle prestazioni inferiore rispetto al modulo di strumentazione automatica.

Esempio

Le istruzioni seguenti mostrano come utilizzare il modulo di strumentazione automatica per Compute Engine e Google Kubernetes Engine.

Compute Engine

Installa i seguenti pacchetti:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Aggiungi il seguente codice all'app per inizializzare e registrare l'utilità di esportazione:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");

// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

GKE

Aggiungi il seguente codice a Dockerfile:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Aggiungi il seguente codice all'app per inizializzare e registrare l'utilità di esportazione:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");

// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Esempio di applicazione che utilizza il framework Express

OpenTelemetry Express Instrumentation consente di raccogliere automaticamente i dati di traccia ed esportarli nel backend che preferisci, offrendoti l'osservabilità dei sistemi distribuiti.

Per utilizzare OpenTelemetry per le applicazioni che usano il framework Express, completa questi passaggi:

1. Installa i seguenti pacchetti:

   npm install --save @opentelemetry/instrumentation-http
   npm install --save @opentelemetry/instrumentation-express
   

2. Aggiungi all'app il seguente codice per caricare tutti i plug-in supportati:

   const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
   const provider = new NodeTracerProvider();
   

Per un esempio di base, vedi l'esempio di OpenTelemetry Express.

Creazione di un intervallo personalizzato

Puoi aggiungere ulteriori informazioni alla traccia creata dal sistema creando un intervallo personalizzato.

Per creare un intervallo personalizzato, aggiungi quanto segue al codice sorgente:

// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
provider.register();
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();

• getTracer restituisce un'istanza del tracciante, dove basic è il nome del tracciante o della libreria di strumentazione. Questo indica a OpenTelemetry chi sta creando gli intervalli.

• foo è il nome dell'intervallo personalizzato.

• invoking work è il nome dell'evento di esempio. Mostra come utilizzare l'API addEvent.

Per un esempio base di creazione di un intervallo personalizzato, vedi l'esempio di OpenTelemetry.

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

In esecuzione su Google Cloud

Quando l'applicazione è in esecuzione su Google Cloud, non è necessario fornire credenziali di autenticazione sotto forma di account di servizio alla libreria client. Tuttavia, devi assicurarti che per la tua piattaforma Google Cloud sia abilitato l'ambito di accesso all'API Cloud Trace.

Per un elenco degli ambienti Google Cloud supportati, consulta Assistenza per l'ambiente.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito dell'accesso abilitano l'Cloud Trace API:

• Ambiente flessibile di App Engine

• Ambiente standard di App Engine

• Google Kubernetes Engine (GKE)

  Nota: se utilizzi Autopilot o se abiliti Workload Identity per il tuo cluster GKE, assicurati di configurare l'applicazione per l'utilizzo di Workload Identity.

• Compute Engine

• Cloud Run

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato:

• Per informazioni su come configurare gli ambiti di accesso per il tuo ambiente utilizzando la console Google Cloud, consulta Configurazione del progetto Google Cloud.

• Per gli utenti gcloud, specifica gli ambiti di accesso utilizzando il flag --scopes e includi l'ambito di accesso all'Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE con solo l&#39Cloud Trace APIe abilitata, segui questi passaggi:

  gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Esecuzione in locale e altrove

Se la tua applicazione è in esecuzione al di fuori di Google Cloud, devi fornire le credenziali di autenticazione alla libreria client sotto forma di account di servizio. L'account di servizio deve contenere il ruolo di agente Cloud Trace. Per le istruzioni, consulta la sezione Creazione di un account di servizio.

Le librerie client di Google Cloud utilizzano Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione.

Puoi fornire queste credenziali in uno dei tre modi seguenti:

• Esegui gcloud auth application-default login

• Inserisci l'account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono elencati i percorsi predefiniti per Windows e Linux:

  • Windows: %APPDATA%/gcloud/application_default_credentials.json

  • Linux: $HOME/.config/gcloud/application_default_credentials.json

• Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del tuo account di servizio:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Visualizza tracce

Nella console Google Cloud, vai alla pagina Esplora tracce.

Vai a Trace Explorer

Puoi trovare questa pagina anche utilizzando la barra di ricerca.

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alla pagina Risoluzione dei problemi.