Node.js e OpenTelemetry

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

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

Per informazioni sulla release, consulta le pagine seguenti:

• Ultima release della libreria per Node.js

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

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

• Tracer
• Span

Per i dettagli più recenti su OpenTelemetry per Node.js, insieme alla documentazione e agli esempi aggiuntivi, consulta OpenTelemetry.

Prima di iniziare

1. Nel pannello di navigazione della console Google Cloud, seleziona API e servizi, fai clic su Abilita API e servizi e poi abilita l'Cloud Trace API:

   Vai alle impostazioni dell'API Cloud Trace

2. Se viene visualizzato API abilitata, significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Installazione, inizializzazione e utilizzo del client

OpenTelemetry offre i seguenti modi per strumentare la tua applicazione:

• Auto-instrumentazione 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 è necessario apportare modifiche al codice delle librerie in uso.

• Tracciamento manuale

  Quando si utilizza questo approccio, si modificano le librerie in uso per raccogliere informazioni sulle tracce.

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

Strumentazione automatica

Il modulo @opentelemetry/sdk-trace-node fornisce l'auto-strumentazione per le applicazioni Node.js.

La strumentazione automatica identifica automaticamente quanto segue 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 il tracciamento pronto all'uso, così non devi apportare modifiche al codice in nessuna delle librerie che stai usando. Il codice di strumentazione compie automaticamente le seguenti azioni:

• Estrae un identificatore di contesto di 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 contesto 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 l'applicazione per produrre intervalli e fornire il tracciamento end-to-end con poche righe di codice.

Strumentazione manuale

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

Esempio

Le seguenti istruzioni 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'esportatore:

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'esportatore:

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));

Applicazione di esempio che utilizza il framework Express

OpenTelemetry Express Instrumentation consente di raccogliere automaticamente i dati di traccia ed esportarli nel backend di tua scelta, garantendo l'osservabilità dei sistemi distribuiti.

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

1. Installa i seguenti pacchetti:

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

2. Aggiungi il seguente codice alla tua app, che carica 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 di tracer, dove basic è il nome dell'utilità di traccia 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. Questo diagramma mostra come utilizzare l'API addEvent.

Per un esempio base sulla 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 la tua applicazione è in esecuzione su Google Cloud, non è necessario fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. 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 la pagina relativa all'assistenza per gli ambienti.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di 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 la tua 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 in cui è abilitata solo l'Cloud Trace API:

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

Esecuzione in locale e altrove

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

Le librerie client di Google Cloud utilizzano le 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 al 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

Nel pannello di navigazione della console Google Cloud, seleziona Trace e poi Trace Explorer:

Vai a Trace Explorer

Risoluzione dei problemi

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