Node.js et OpenTelementry

Cette page est destinée aux développeurs d'applications qui souhaitent collecter des données Cloud Trace pour les applications Node.js à l'aide d'OpenTelemetry. OpenTelemetry est un ensemble de bibliothèques d'instrumentation permettant de collecter des données de trace et de métrique. Ces bibliothèques fonctionnent avec plusieurs backends. Pour collecter des traces avec OpenTelemetry et Node.js, procédez comme suit, comme décrit sur cette page:

  • Installez les packages OpenTelemetry.
  • Configurez votre application pour exporter les délais vers Cloud Trace.
  • Configurez votre plate-forme.

Pour obtenir des informations sur la version, consultez les pages suivantes:

Pour obtenir les dernières informations sur OpenTelemetry pour Node.js, ainsi que des documents et des exemples supplémentaires, consultez la page OpenTelemetry.

Avant de commencer

Vérifiez que l'API Cloud Trace est activée pour votre projet Google Cloud:

  1. Cliquez sur le bouton suivant ou, dans Google Cloud Console, sélectionnez API et services, puis API Cloud Trace:

    Accéder à l'API Trace

  2. Sur la page API Cloud Trace, si un bouton Activer s'affiche, cliquez dessus. Si ce bouton ne s'affiche pas, l'API Cloud Trace est activée pour le projet sélectionné.

Installer, initialiser et utiliser le client

OpenTelementry propose trois méthodes pour instrumenter votre application :

  • Instrumentation automatique pour les applications Node.js
  • Traçage manuel
  • Instrumentation automatique pour les applications Web

Les sections suivantes présentent le cas d'utilisation de chaque instrumentation.

Instrumentation automatique

Le module @opentelemetry/node fournit une instrumentation automatique pour les applications Node.js.

L'instrumentation automatique identifie automatiquement les éléments suivants dans votre application :

  • Frameworks, tels que Express
  • Protocoles courants, tels que HTTP, HTTPS et gRPC
  • Bases de données, telles que MySQL, MongoDB, Redis et PostgreSQL
  • Autres bibliothèques au sein de votre application

L'instrumentation automatique fournit un traçage prêt à l'emploi. Vous n'avez donc pas besoin de modifier le code des bibliothèques que vous utilisez. Le code d'instrumentation effectue automatiquement les actions suivantes :

  • Extrait un identifiant de contexte de trace des requêtes entrantes pour permettre le traçage distribué, le cas échéant.
  • Garantit que le contexte de trace actuel est propagé pendant que la transaction balaie une application.
  • Ajoute l'identifiant de contexte de trace aux requêtes sortantes, ce qui permet à la trace distribuée de passer au saut suivant, le cas échéant.
  • Crée et termine des délais.

Le module utilise des plug-ins pour instrumenter automatiquement votre application afin de générer des délais et de fournir un traçage de bout en bout avec seulement quelques lignes de code.

Instrumentation manuelle

Le module de traçage manuel, @opentelementry/tracing, offre un contrôle total sur l'instrumentation et la création de délais. Il ne charge pas async_hooks. Il n'utilise pas de stockage local de continuation ni de plug-in d'instrumentation par défaut. Le traçage manuel a moins d'impact sur les performances que le module d'instrumentation automatique.

Instrumentation automatique pour les applications Web

Le module @opentelementry/web fournit une instrumentation et un traçage automatisés pour les applications Web. Il collecte les données de performances côté utilisateur, y compris la latence et les traces distribuées, ce qui vous permet de diagnostiquer les problèmes d'interface et de surveiller l'état général de l'application.

Les instructions suivantes montrent comment utiliser le module d'instrumentation automatique pour Compute Engine et Google Kubernetes Engine.

Instance

Installez les packages suivants :

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

Ajoutez le code suivant à votre application pour initialiser et enregistrer l'exportateur :

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = 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 send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

GKE

Ajoutez les éléments suivants au fichier Dockerfile :

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

Ajoutez le code suivant à votre application pour initialiser et enregistrer l'exportateur :

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = 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 send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

Exemple d'application utilisant le framework Express

OpenTelemetry Express Instrumentation vous permet de collecter automatiquement les données de trace et de les exporter vers le backend de votre choix, ce qui vous donne une visibilité sur les systèmes distribués.

Pour utiliser OpenTelemetry pour les applications qui utilisent le framework Express, procédez comme suit :

  1. Installez les packages suivants :

    npm install --save @opentelemetry/plugin-http
    npm install --save @opentelemetry/plugin-express
    
  2. Ajoutez à votre application le code suivant, qui charge tous les plug-ins compatibles :

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

Pour obtenir un exemple de base, consultez l'exemple OpenTelemetry Express.

Créer un délai personnalisé

Vous pouvez ajouter des informations supplémentaires à la trace créée par le système en créant un délai personnalisé.

Pour créer un délai personnalisé, ajoutez les éléments suivants au code source :


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
opentelemetry.trace.setGlobalTracerProvider(provider);
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 renvoie une instance de traceur, où basic est le nom du traceur ou de la bibliothèque d'instrumentation. Cela indique à OpenTelemetry qui crée des délais.

  • foo est le nom du délai personnalisé.

  • invoking work est le nom de l'exemple d'événement. Cela montre comment utiliser l'API addEvent.

Pour obtenir un exemple de base de création d'un délai personnalisé, consultez l'exemple OpenTelemetry.

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécuter des applications sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.

Pour obtenir la liste des environnements Google Cloud compatibles, consultez la page Environnements compatibles.

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

  • Environnement flexible App Engine
  • Environnement standard App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Si vous utilisez des champs d'application d'accès personnalisés, vous devez vous assurer que le champ d'application de l'accès à l'API Cloud Trace est activé:

  • Pour en savoir plus sur la configuration des niveaux d'accès pour votre environnement à l'aide de Google Cloud Console, consultez la page Configurer votre projet Google Cloud.

  • Pour les utilisateurs gcloud, spécifiez des niveaux d'accès à l'aide de l'option --scopes et spécifiez le niveau d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :

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

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous fournissez ces identifiants en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS :

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"

Afficher les traces

Après le déploiement, vous pouvez afficher les traces dans la visionneuse de traces de Cloud Console.

Accéder à la page Lecteur de traces

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.