Monitoring des traces Node.js avec ClickStack

Cette section explique comment ajouter le traçage distribué à votre application Node.js existante à l’aide de l’instrumentation automatique d’OpenTelemetry.

Si vous souhaitez tester l’intégration avant de configurer votre propre environnement, vous pouvez l’essayer avec notre configuration préconfigurée et des données d’exemple dans la section du jeu de données de démonstration.

• Instance ClickStack en cours d’exécution avec des endpoints OTLP accessibles (ports 4317/4318)
• Application Node.js existante (Node.js 14 ou version ultérieure)
• Gestionnaire de paquets npm ou yarn
• Nom d’hôte ou adresse IP de ClickStack

Installer et configurer OpenTelemetry

Installez le paquet @hyperdx/node-opentelemetry et initialisez-le au démarrage de votre application. Consultez le guide du SDK Node.js pour obtenir les étapes d’installation détaillées.

Obtenir une clé API ClickStack

Une clé API est nécessaire pour envoyer des traces vers le point de terminaison OTLP de ClickStack.

1. Ouvrez HyperDX à l’URL de votre instance ClickStack (par exemple, http://localhost:8080)
2. Créez un compte ou connectez-vous si nécessaire
3. Accédez à Team Settings → API Keys
4. Copiez votre clé API d’ingestion

Exécuter votre application

Démarrez votre application Node.js avec les variables d’environnement définies :

export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Générer du trafic

Envoyez des requêtes à votre application pour générer des traces :

# Requêtes simples
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products

# Simuler de la charge
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done

Vérifier les traces dans HyperDX

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les traces remontent correctement. Vous devriez voir quelque chose comme ceci. Si vous ne voyez pas de traces, essayez d’ajuster votre intervalle de temps :

Cliquez sur une trace pour afficher la vue détaillée avec les spans, les durées et les attributs :

Pour les utilisateurs qui souhaitent tester le tracing Node.js avec ClickStack avant d’instrumenter leurs applications de production, nous fournissons un jeu de données d’exemple contenant des traces d’applications Node.js pré-générées avec des schémas de trafic réalistes.

Télécharger le jeu de données d’exemple

Téléchargez le fichier de traces d’exemple :

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json

Démarrer ClickStack

Si ClickStack n’est pas encore démarré, lancez-le avec :

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  clickhouse/clickstack-all-in-one:latest

Obtenir une clé API ClickStack

Vous avez besoin d’une clé API pour envoyer des traces vers le point de terminaison OTLP de ClickStack.

1. Ouvrez HyperDX à l’URL de votre instance ClickStack (par ex. http://localhost:8080)
2. Créez un compte ou connectez-vous si nécessaire
3. Accédez à Team Settings → API Keys
4. Copiez votre clé API d’ingestion

Définissez votre clé API comme variable d’environnement :

export CLICKSTACK_API_KEY=your-api-key-here

Envoyer les traces vers ClickStack

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

Vous devriez voir une réponse comme {"partialSuccess":{}}, indiquant que les traces ont bien été envoyées.

Vérifier les traces dans HyperDX

1. Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
2. Accédez à la vue Search et définissez la source sur Traces
3. Définissez l’intervalle de temps sur 2025-10-25 13:00:00 - 2025-10-28 13:00:00

Pour vous aider à commencer à surveiller les performances de l’application Node.js, nous fournissons un tableau de bord préconfiguré avec les visualisations de traces essentielles.

Télécharger la configuration du tableau de bord

Télécharger le fichier de configuration du tableau de bord.

Importer le tableau de bord préconfiguré

1. Ouvrez HyperDX et accédez à la section Dashboards
2. Cliquez sur Import Dashboard dans l’angle supérieur droit (sous les points de suspension)

3. Téléversez le fichier nodejs-traces-dashboard.json, puis cliquez sur Finish Import

Le tableau de bord sera créé avec toutes les visualisations préconfigurées

Si vous avez envoyé des traces via curl mais qu’elles n’apparaissent pas dans HyperDX, essayez de les renvoyer une seconde fois :

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

Il s’agit d’un problème connu qui se produit avec la méthode de démonstration via curl et n’affecte pas les applications de production instrumentées.

Vérifiez que les variables d’environnement sont bien définies :

echo $CLICKSTACK_API_KEY
# Should output your API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Should output http://localhost:4318 or your ClickStack host

Vérifiez la connectivité réseau :

curl -v http://localhost:4318/v1/traces

L’application devrait se connecter correctement à l’endpoint OTLP.

Vérifiez les logs de l’application : Recherchez des messages d’initialisation d’OpenTelemetry au démarrage de votre application. Le SDK HyperDX devrait afficher une confirmation de son initialisation.

• Configurez des alertes pour les métriques critiques (taux d’erreur, seuils de latence)
• Créez des tableaux de bord supplémentaires pour des cas d’usage spécifiques (supervision des API, événements de sécurité)

Ce guide utilise le SDK HyperDX, qui envoie les traces directement vers le point de terminaison OTLP de ClickStack. Cette approche convient bien au développement, aux tests et aux déploiements en production de petite à moyenne taille. Pour des environnements de production plus importants, ou si vous avez besoin d'un contrôle plus fin sur les données de télémétrie, envisagez de déployer votre propre OpenTelemetry Collector en tant qu’agent. Consultez Ingestion avec OpenTelemetry pour les modèles de déploiement en production et des exemples de configuration du collecteur.