Node.js

SDK Node.js pour ClickStack - la stack d’observabilité de ClickHouse

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

​

Premiers pas

​

Installez le paquet d’instrumentation OpenTelemetry d’HyperDX

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

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

Initialisation du SDK

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

require

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

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.

​

Configurer la collecte des logs

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

Winston

Si vous utilisez winston comme logger, vous devrez ajouter le transport suivant à votre logger.

    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;

Pino

Si vous utilisez pino comme logger, vous devrez ajouter le transport suivant à votre logger et spécifier un mixin pour corréler les logs avec les traces.

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;

console.log

Par défaut, les méthodes console.* sont prises en charge nativement. Aucune configuration supplémentaire n’est requise.

Vous pouvez désactiver ce comportement en définissant la variable d’environnement HDX_NODE_CONSOLE_CAPTURE sur 0 ou en passant consoleCapture: false à la fonction init.

​

Configurer la collecte des erreurs

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.

Express

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

Koa

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

Manuel

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

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

​

Dépannage

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

​

Configuration avancée de l’instrumentation

​

Capturer les logs de la console

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.

copy

export HDX_NODE_CONSOLE_CAPTURE=0

​

Ajouter des informations utilisateur ou des métadonnées

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

​

Google Cloud Run

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.

​

Bibliothèques auto-instrumentées

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

​

Autre méthode d’installation

​

Exécuter l’application avec la CLI OpenTelemetry de ClickStack

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.

Avec NPX

Managed ClickStack

La variable HYPERDX_API_KEY peut être omise avec Managed ClickStack.

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

Point d’entrée personnalisé (ex. Nodemon, ts-node, etc.)

Managed ClickStack

La variable HYPERDX_API_KEY peut être omise avec Managed ClickStack.

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

Importation du code

// 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.

​

Activer la capture des exceptions

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.

​

Bibliothèques auto-instrumentées

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