Exemple d'instrumentation Node.js

Ce document explique comment instrumenter une application JavaScript Node.js pour collecter des données de trace et de métrique à l'aide du SDK OpenTelemetry et d'un collecteur OpenTelemetry. Il explique également comment écrire des journaux JSON structurés dans la sortie standard. Pour tester l'instrumentation, téléchargez et exécutez l'application exemple. Cette application utilise le framework Web Fastify et génère des données de journaux, de métriques et de traces.

Lorsque vous utilisez un collecteur OpenTelemetry, vous instrumentez votre application avec le SDK et l'exportateur OTLP intégré au SDK. Cette instrumentation est indépendante du fournisseur. Vous déployez également un collecteur OpenTelemetry qui reçoit les données de télémétrie de l'exportateur intégré, puis les exporte vers votre projet Google Cloud . Pour en savoir plus sur les collecteurs, consultez Collecteur OpenTelemetry conçu par Google.

Nous vous recommandons d'utiliser un collecteur OpenTelemetry pour exporter vos données de télémétrie lorsque votre environnement est compatible avec l'utilisation d'un collecteur. Pour certains environnements, vous devez utiliser un exportateur intégré qui envoie directement les données à votre projetGoogle Cloud . Pour en savoir plus sur l'instrumentation intégrée, consultez Migrer de l'exportateur de trace vers le point de terminaison OTLP.

Pour en savoir plus sur l'instrumentation, consultez les documents suivants :

À propos de l'instrumentation manuelle et sans code

Pour ce langage, OpenTelemetry définit l'instrumentation sans code comme une pratique consistant à collecter des données de télémétrie à partir de bibliothèques et de frameworks sans modifier le code. En revanche, vous devez installer des modules et définir des variables d'environnement.

Ce document ne décrit pas l'instrumentation sans code. Pour en savoir plus à ce sujet, consultez Instrumentation JavaScript sans code.

Pour obtenir des informations générales, consultez Instrumentation OpenTelemetry pour Node.js.

Avant de commencer

Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Créez un projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

Vérifiez que la facturation est activée pour votre projet Google Cloud .

Activez les API Cloud Logging, Cloud Monitoring, Cloud Trace et Télémétrie :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Créez un projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

Vérifiez que la facturation est activée pour votre projet Google Cloud .

Activez les API Cloud Logging, Cloud Monitoring, Cloud Trace et Télémétrie :

Rôles requis pour activer les API

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Si vous exécutez l'exemple dans Cloud Shell, sur des ressources Google Cloudou dans un environnement de développement local, les autorisations listées dans cette section sont suffisantes. Pour les applications de production, un compte de service fournit généralement les identifiants permettant d'écrire des données de journaux, de métriques et de trace.

Pour obtenir les autorisations nécessaires pour que l'application exemple écrive des données de journaux, de métriques et de trace, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :
- Rédacteur de journaux (roles/logging.logWriter)
- Rédacteur de métriques Monitoring (roles/monitoring.metricWriter)
- Rédacteur de traces de télémétrie cloud (roles/telemetry.tracesWriter)
Pour obtenir les autorisations nécessaires pour afficher vos données de journaux, de métriques et de traces, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :
- Lecteur de journaux (roles/logging.viewer)
- Lecteur Monitoring (roles/monitoring.viewer)
- Utilisateur Cloud Trace (roles/cloudtrace.user)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Instrumenter votre application pour collecter des traces, des métriques et des journaux

Pour instrumenter votre application afin de collecter des données de trace et de métrique, et d'écrire un code JSON structuré pour la sortie standard, procédez comme suit, comme décrit dans les sections suivantes de ce document:

Configurer OpenTelementry
Configurer votre application pour précharger la configuration OpenTelemetry
Configurer la journalisation structurée
Écrire des journaux structurés

Configurer OpenTelementry

La configuration par défaut du SDK OpenTelemetry Node.js exporte les traces à l'aide du protocole OTLP. Il configure également OpenTelemetry afin d'utiliser le format Contexte de trace W3C pour propager le contexte de trace. Cette configuration garantit que les délais ont la bonne relation parent-enfant au sein d'une trace.

L'exemple de code suivant illustre un module JavaScript permettant de configurer OpenTelemetry.

Pour afficher l'exemple complet, cliquez sur Plus, puis sélectionnez Afficher sur GitHub.


diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.diagLogLevelFromString(
    opentelemetry.core.getStringFromEnv('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'exemple de code précédent configure OpenTelemetry pour exporter des métriques à l'aide du protocole OTLP et utilise le package @opentelemetry/auto-instrumentations-node pour configurer toutes les instrumentations Node.js disponibles.

Pour garantir que toutes les données de télémétrie en attente sont vidées et que les connexions sont fermées correctement avant l'arrêt de l'application, le gestionnaire SIGTERM appelle shutdown.

Pour en savoir plus et découvrir les options de configuration, consultez Configuration de l'instrumentation sans code.

Configurer votre application pour précharger la configuration OpenTelemetry

Pour configurer l'application afin qu'elle écrive des journaux structurés et pour collecter des métriques et des données de trace à l'aide d'OpenTelemetry, mettez à jour l'appel de votre application pour précharger le module d'instrumentation avec Node.jsoption --require. L'option --require garantit qu'OpenTelemetry est initialisé avant le démarrage de votre application. Pour en savoir plus, consultez la page Premiers pas avec OpenTelemetry Node.js.

L'exemple de code suivant illustre un fichier Dockerfile transmettant l'option --require:

CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

Configurer la journalisation structurée

Pour inclure les informations de trace dans les journaux au format JSON écrits dans la sortie standard, configurez votre application de sorte qu'elle génère des journaux structurés au format JSON.

L'exemple de code suivant illustre un objet Pino LoggerOptions qui configure l'application pour générer des journaux structurés 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 configuration précédente extrait des informations sur le délai actif du message de journal, puis ajoute ces informations en tant qu'attributs au journal structuré JSON. Ces attributs peuvent ensuite être utilisés pour mettre en corrélation un journal et une trace:

logging.googleapis.com/trace: nom de ressource de la trace associée à l'entrée de journal.
logging.googleapis.com/spanId: ID de délai avec la trace associée à l'entrée de journal.
logging.googleapis.com/trace_sampled: la valeur de ce champ doit être true ou false.

Pour en savoir plus sur ces champs, consultez la structure LogEntry.

Pour utiliser la configuration Pino avec Fastify, transmettez l'objet de configuration de l'enregistreur lors de la création de l'application Fastify:

// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

Écrire des journaux structurés

Pour écrire des journaux structurés qui renvoient vers une trace, utilisez l'enregistreur Pino fourni par Fastify. Par exemple, l'instruction suivante montre comment appeler la méthode Logger.info():

request.log.info({subRequests}, 'handle /multi request');

OpenTelemetry renseigne automatiquement les entrées de journal Pino avec le contexte de segment du délai actif actuel dans le contexte OpenTelemetry. Ce contexte de segment est ensuite inclus dans les journaux JSON, comme décrit dans la section Configurer la journalisation structurée.

Exécuter un exemple d'application configuré pour collecter les données de télémétrie

L'instrumentation de l'application exemple utilise des formats neutres du point de vue du fournisseur, comme JSON pour les données de journaux et OTLP pour les données de métriques et de traces. L'application utilise également le framework Fastify. L'Collector OpenTelemetry envoie des données de journaux et de métriques à votre projet à l'aide d'exportateurs Google. Il envoie vos données de trace à votre projet à l'aide de l'API Telemetry, qui utilise OTLP.

L'application possède deux points de terminaison:

Le point de terminaison /multi est géré par la fonction handleMulti. Le générateur de charge de l'application envoie des requêtes au point de terminaison /multi. Lorsque ce point de terminaison reçoit une requête, il envoie entre trois et sept requêtes au point de terminaison /single sur le serveur local.

/**
 * 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';
});

Le point de terminaison /single est géré par la fonction handleSingle. Lorsque ce point de terminaison reçoit une requête, il reste en veille pendant un court délai, puis répond par une chaîne.

/**
 * 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`;
});

Télécharger et déployer l'application

Pour exécuter l'exemple , procédez comme suit :

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell

En bas de la console Google Cloud , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

Clonez le dépôt :

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js

Accédez au répertoire de l'exemple :

cd opentelemetry-operations-js/samples/instrumentation-quickstart

Compilez et exécutez l'exemple.

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

Si vous n'exécutez pas sur Cloud Shell, exécutez l'application avec la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pointant vers un fichier d'identifiants. Les identifiants par défaut de l'application fournissent un fichier d'identifiants à l'adresse $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

Afficher vos métriques

L'instrumentation OpenTelementry dans l'exemple d'application génère des métriques Prometheus que vous pouvez afficher à l'aide de l'explorateur de métriques:

Prometheus/http_server_duration_milliseconds/histogram enregistre la durée des requêtes du serveur et stocke les résultats dans un histogramme.
Prometheus/http_client_duration_milliseconds/histogram enregistre la durée des requêtes des clients et stocke les résultats dans un histogramme.

Pour afficher les métriques générées par l'exemple d'application, procédez comme suit :

Dans la console Google Cloud , accédez à la page Explorateur de métriques.
Accéder à l'Explorateur de métriques

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.
Dans la barre d'outils de la console Google Cloud , sélectionnez votre projet Google Cloud . Pour les configurations App Hub, sélectionnez le projet hôte App Hub ou le projet de gestion du dossier compatible avec les applications.
Dans l'élément Métrique, développez le menu Sélectionner une métrique, saisissez http_server dans la barre de filtre, puis utilisez les sous-menus pour sélectionner un type de ressource et des métriques spécifiques :
1. Dans le menu Ressources actives, sélectionnez Cible Prometheus.
2. Dans le menu Catégories de métriques actives, sélectionnez Http.
3. Dans le menu Métriques actives, sélectionnez une métrique.
4. Cliquez sur Appliquer.
Pour ajouter des filtres qui suppriment des séries temporelles des résultats de la requête, utilisez l'élément Filtre.
Configurez le mode d'affichage des données.
Lorsque les mesures d'une métrique sont cumulatives, l'explorateur de métriques normalise automatiquement les données mesurées par période d'alignement, ce qui permet d'afficher un taux dans le graphique. Pour en savoir plus, consultez la section Genres, types et conversions.

Lorsque des valeurs entières ou doubles sont mesurées, par exemple avec les deux métriques counter, l'explorateur de métriques additionne automatiquement toutes les séries temporelles. Pour afficher les données des routes HTTP /multi et /single, définissez le premier menu de l'entrée Agrégation sur Aucun.

Pour plus d'informations sur la configuration d'un graphique, consultez la page Sélectionner des métriques lors de l'utilisation de l'explorateur de métriques.

Afficher vos traces

L'affichage de vos données de trace peut prendre plusieurs minutes. Par exemple, lorsque des données de trace sont reçues par votre projet, Google Cloud Observability peut avoir besoin de créer une base de données pour les stocker. La création de la base de données peut prendre quelques minutes. Pendant cette période, aucune donnée de trace n'est disponible.

Pour afficher vos données de trace, procédez comme suit:

Dans la console Google Cloud , accédez à la page Explorateur Trace :
Accéder à Explorateur Trace

Vous pouvez également accéder à cette page à l'aide de la barre de recherche.
Dans la section du tableau de la page, sélectionnez une ligne avec le nom de portée /multi.
Dans le graphique de Gantt du panneau Détails des traces, sélectionnez le délai intitulé /multi.

Un panneau contenant des informations sur la requête HTTP s'affiche. Ces informations incluent la méthode, le code d'état, le nombre d'octets et le user-agent de l'appelant.
Pour afficher les journaux associés à cette trace, sélectionnez l'onglet Logs & Events (Journaux et événements).

Cet onglet affiche les journaux individuels. Pour afficher les détails de l'entrée de journal, développez-la. Vous pouvez également cliquer sur Afficher les journaux et afficher le journal à l'aide de l'explorateur de journaux.

Pour en savoir plus sur l'utilisation de l'explorateur Cloud Trace, consultez la page Rechercher et explorer des traces.

Afficher les journaux

L'explorateur de journaux vous permet d'inspecter vos journaux et d'afficher les traces associées, lorsqu'elles existent.

Dans la console Google Cloud , accédez à la pageExplorateur de journaux :
Accéder à l'explorateur de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.
Recherchez un journal avec la description suivante : handle /multi request.

Pour afficher les détails du journal, développez l'entrée de journal.
Cliquez sur Traces sur une entrée de journal contenant le message "handle /multi request", puis sélectionnez Afficher les détails des traces.

Un panneau Trace details (Informations sur la trace) s'ouvre et affiche la trace sélectionnée.

Vos données de journaux peuvent être disponibles plusieurs minutes avant vos données de trace. Si vous rencontrez une erreur lors de l'affichage des données de trace, que ce soit en recherchant une trace par ID ou en suivant les étapes de cette tâche, attendez une ou deux minutes, puis réessayez.

Pour en savoir plus sur l'utilisation de l'explorateur de journaux, consultez Afficher les journaux à l'aide de l'explorateur de journaux.