Configurer Cloud Trace pour Node.js

Vous pouvez activer Cloud Trace pour les applications Node.js à l'aide de la bibliothèque Cloud Trace pour Node.js.

Installer la bibliothèque cliente

  1. Avant d'installer la bibliothèque Cloud Trace pour Node.js, assurez-vous d'avoir préparé votre environnement pour le développement Node.js.

  2. Pour installer la bibliothèque Cloud Trace pour Node.js, utilisez npm :

    npm install --save @google-cloud/trace-agent

  3. Importez la bibliothèque Cloud Trace pour Node.js en haut du script principal ou du point d'entrée de votre application avant tout autre code :

    require('@google-cloud/trace-agent').start();

Pour en savoir plus ou pour signaler des problèmes liés à la bibliothèque Cloud Trace pour Node.js, consultez le dépôt GitHub cloud-trace-nodejs de l'agent.

Configurer la bibliothèque cliente

Vous pouvez personnaliser le comportement de la bibliothèque Cloud Trace pour Node.js. Consultez la configuration de la bibliothèque sur GitHub pour obtenir la liste des options de configuration que vous pouvez transmettre à la méthode start de la bibliothèque à l'aide d'un objet options.

L'exemple suivant montre comment spécifier l'ID du projet Google Cloud et définir le chemin d'accès à votre fichier d'identifiants. Ces deux instructions sont facultatives lorsque vous utilisez Google Cloud :

require('@google-cloud/trace-agent').start({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Si vous utilisez une infrastructure Google Cloud, vous n'avez pas besoin de définir projectId sur votre ID de projet Google Cloud. Si vous ne définissez pas ce champ, la bibliothèque cliente pour Node.js collecte automatiquement ces données à partir d'un serveur de métadonnées Google Cloud.

Si vous n'exécutez pas sur l'infrastructure Google Cloud, vous devez fournir l'ID de votre projet Google Cloud à votre application.

Quelle que soit votre infrastructure, pour Node.js, lorsque vous ne définissez pas explicitement l'ID du projet Google Cloud, la bibliothèque cloud-trace-nodejs détermine automatiquement si la variable d'environnement GCLOUD_PROJECT est définie et, le cas échéant, utilise la valeur de GCLOUD_PROJECT comme ID de projet Google Cloud. Pour en savoir plus sur le fichier de découverte, accédez à cloud-trace-nodejs/src/index. Pour définir la variable d'environnement, procédez comme suit :

Linux ou macOS

export GCLOUD_PROJECT=your-project-id

Windows

set GCLOUD_PROJECT=your-project-id

Powershell :

$env:GCLOUD_PROJECT="your-project-id"

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 niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé :

  • Pour savoir comment configurer les niveaux d'accès à votre environnement à l'aide de Google Cloud Console, consultez la section Configurer votre projet Google Cloud.

  • Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'indicateur --scopes et incluez 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 pouvez fournir ces identifiants de trois manières différentes:

  • Exécuter gcloud auth application-default login

  • Placez le compte de service dans un chemin d'accès par défaut pour votre système d'exploitation. Vous trouverez ci-dessous la liste des chemins par défaut pour Windows et Linux:

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

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

  • Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès à votre compte de service:

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"

Exemple d'application

if (process.env.NODE_ENV === 'production') {
  require('@google-cloud/trace-agent').start();
}

const express = require('express');
const got = require('got');

const app = express();
const DISCOVERY_URL = 'https://www.googleapis.com/discovery/v1/apis';

// This incoming HTTP request should be captured by Trace
app.get('/', async (req, res) => {
  // This outgoing HTTP request should be captured by Trace
  try {
    const {body} = await got(DISCOVERY_URL, {responseType: 'json'});
    const names = body.items.map(item => item.name);
    res.status(200).send(names.join('\n')).end();
  } catch (err) {
    console.error(err);
    res.status(500).end();
  }
});

// Start the server
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

Afficher les traces

Après le déploiement, vous pouvez afficher les traces dans le lecteur de traces de la 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.

Resources