Node.js

ClickStack utilise la norme OpenTelemetry pour collecter les données de télémétrie (logs, metrics, traces et exceptions). Les traces sont générées automatiquement grâce à l’instrumentation automatique, donc une instrumentation manuelle n’est pas nécessaire pour bénéficier du tracing.

Ce guide intègre :

• Logs
• Metrics
• Traces
• Exceptions

Utilisez la commande suivante pour installer le paquet OpenTelemetry de ClickStack.

npm install @hyperdx/node-opentelemetry 

yarn add @hyperdx/node-opentelemetry 

Pour initialiser le SDK, vous devez appeler la fonction init au début du fichier d’entrée de votre application.

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omettre pour Managed ClickStack
    service: 'my-service'
});

import * as HyperDX from '@hyperdx/node-opentelemetry';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omettre pour Managed ClickStack
    service: 'my-service'
});

Cela capturera automatiquement les traces, les métriques et les logs de votre application Node.js.

Par défaut, les logs console.* sont collectés. Si vous utilisez un logger comme winston ou pino, vous devrez ajouter un transport à votre logger pour envoyer les logs à ClickStack. Si vous utilisez un autre type de logger, n'hésitez pas à nous contacter ou à consulter l'une de nos intégrations de plateforme, le cas échéant (par exemple Kubernetes).

    import winston from 'winston';
    import * as HyperDX from '@hyperdx/node-opentelemetry';

    const logger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        new winston.transports.Console(),
        HyperDX.getWinstonTransport('info', { // Envoie les logs de niveau info et supérieurs
          detectResources: true,
        }),
      ],
    });

    export default logger;

import pino from 'pino';
import * as HyperDX from '@hyperdx/node-opentelemetry';

const logger = pino(
    pino.transport({
    mixin: HyperDX.getPinoMixinFunction,
    targets: [
        HyperDX.getPinoTransport('info', { // Envoie les logs de niveau info et supérieurs
        detectResources: true,
        }),
    ],
    }),
);

export default logger;

Le SDK ClickStack peut capturer automatiquement les exceptions non gérées et les erreurs de votre application, avec la stack trace complète et le contexte du code.

Pour l’activer, vous devez ajouter le code suivant à la fin du middleware de gestion des erreurs de votre application, ou capturer manuellement les exceptions à l’aide de la fonction recordException.

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // À omettre pour Managed ClickStack
    service: 'my-service'
});
const app = express();

// Ajoutez vos routes, etc.

// Ajoutez ceci après toutes les routes,
// mais avant de définir tout autre middleware de gestion des erreurs
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // À omettre pour Managed ClickStack
    service: 'my-service'
});

const router = new Router();
const app = new Koa();

HyperDX.setupKoaErrorHandler(app);

// Ajoutez vos routes, etc.

app.listen(3030);

const HyperDX = require('@hyperdx/node-opentelemetry');

function myErrorHandler(error, req, res, next) {
    // Peut être utilisé n'importe où dans votre application
    HyperDX.recordException(error);
}

Si vous rencontrez des difficultés avec le SDK, vous pouvez activer la journalisation détaillée en définissant la variable d’environnement OTEL_LOG_LEVEL sur debug.

export OTEL_LOG_LEVEL=debug

Par défaut, le SDK ClickStack capture les logs de la console. Vous pouvez désactiver cette fonctionnalité en définissant la variable d'environnement HDX_NODE_CONSOLE_CAPTURE sur 0.

export HDX_NODE_CONSOLE_CAPTURE=0

Pour marquer facilement tous les événements liés à un attribut ou à un identifiant donné (par ex. l'ID utilisateur ou l'e-mail), vous pouvez appeler la fonction setTraceAttributes, qui appliquera les attributs déclarés à chaque log/span associé à la trace en cours après l'appel. Il est recommandé d'appeler cette fonction le plus tôt possible dans une requête/trace donnée (par ex. le plus tôt possible dans une pile de middlewares Express).

C'est un moyen pratique de garantir que tous les logs/spans sont automatiquement marqués avec les bons identifiants pour pouvoir les rechercher plus tard, au lieu de devoir marquer et propager manuellement les identifiants vous-même.

userId, userEmail, userName et teamName renseigneront l'UI des sessions avec les valeurs correspondantes, mais peuvent être omis. Toute valeur supplémentaire peut être spécifiée et utilisée pour rechercher des événements.

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // Get user information from the request...

  // Attach user information to the current trace
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

Veillez à activer le mode bêta en définissant la variable d’environnement HDX_NODE_BETA_MODE sur 1, ou en passant betaMode: true à la fonction init afin d’activer les attributs de trace.

export HDX_NODE_BETA_MODE=1

Si votre application s’exécute sur Google Cloud Run, Cloud Trace injecte automatiquement des headers d’échantillonnage dans les requêtes entrantes, ce qui limite actuellement l’échantillonnage des traces à 0,1 requête par seconde pour chaque instance.

Le paquet @hyperdx/node-opentelemetry définit toutefois par défaut le taux d’échantillonnage sur 1,0.

Pour modifier ce comportement ou configurer d’autres installations OpenTelemetry, vous pouvez définir manuellement les variables d’environnement OTEL_TRACES_SAMPLER=parentbased_always_on et OTEL_TRACES_SAMPLER_ARG=1 afin d’obtenir le même résultat.

Pour en savoir plus et forcer le traçage de requêtes spécifiques, consultez la documentation Google Cloud Run.

Les bibliothèques suivantes seront automatiquement instrumentées (avec traçage) par le SDK :

• dns
• express
• graphql
• hapi
• http
• ioredis
• knex
• koa
• mongodb
• mongoose
• mysql
• mysql2
• net
• pg
• pino
• redis
• winston

Vous pouvez également auto-instrumenter votre application sans modifier le code en utilisant la CLI opentelemetry-instrument ou l’option Node.js --require. L’installation de la CLI offre un plus large éventail de bibliothèques et de frameworks auto-instrumentés.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js

// Importez ceci tout en haut du premier fichier chargé par votre application
// Vous indiquerez toujours votre clé API via la variable d’environnement `HYPERDX_API_KEY`
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // facultatif, par défaut : true
    additionalInstrumentations: [], // facultatif, par défaut : []
});

La variable d’environnement OTEL_SERVICE_NAME est utilisée pour identifier votre service dans l’application HyperDX. Elle peut avoir le nom de votre choix.

Pour activer la capture des exceptions non gérées, vous devrez définir la variable d’environnement HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE sur 1.

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

Ensuite, pour collecter automatiquement les exceptions d’Express ou de Koa, ou pour les intercepter manuellement, suivez les instructions de la section Configurer la collecte des erreurs ci-dessus.

Les bibliothèques suivantes seront instrumentées automatiquement (pour le traçage) via les méthodes d’installation ci-dessus :

• amqplib
• AWS Lambda Functions
• aws-sdk
• bunyan
• cassandra-driver
• connect
• cucumber
• dataloader
• dns
• express
• fastify
• generic-pool
• graphql
• grpc
• hapi
• http
• ioredis
• knex
• koa
• lru-memoizer
• memcached
• mongodb
• mongoose
• mysql
• mysql2
• nestjs-core
• net
• pg
• pino
• redis
• restify
• socket.io
• winston