> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Monitoring des traces Node.js avec ClickStack > Monitoring des traces d'applications Node.js avec ClickStack export const TrackedLink = ({href, eventName, children, ...rest}) => { const handleClick = () => { try { if (typeof window !== "undefined" && window.galaxy && eventName) { window.galaxy.track(eventName, { interaction: "click" }); } } catch (e) {} }; return {children} ; }; export const Image = ({img, alt, size = "lg"}) => { const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg"; return

; }; **En bref** Collectez les traces distribuées d’applications Node.js dans ClickStack à l’aide de l’instrumentation automatique d’OpenTelemetry. Comprend un jeu de données de démonstration et un tableau de bord préconfiguré.

## Intégration à une application Node.js existante

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](#demo-dataset).

##### Prérequis

* 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 Installez le paquet `@hyperdx/node-opentelemetry` et initialisez-le au démarrage de votre application. Consultez le [guide du SDK Node.js](/docs/fr/clickstack/ingesting-data/sdks/nodejs#getting-started) pour obtenir les étapes d’installation détaillées. 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](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** Clé API ClickStack

Démarrez votre application Node.js avec les variables d’environnement définies : ```bash theme={null} export CLICKSTACK_API_KEY=your-api-key-here export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 ``` Envoyez des requêtes à votre application pour générer des traces : ```bash theme={null} # 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 ``` 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 : Vue de recherche des traces

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

## Jeu de données de démonstration

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échargez le fichier de traces d’exemple : ```bash theme={null} curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json ``` Si ClickStack n’est pas encore démarré, lancez-le avec : ```bash theme={null} 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 ``` 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](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** Clé API ClickStack

Définissez votre clé API comme variable d’environnement : ```bash theme={null} export CLICKSTACK_API_KEY=your-api-key-here ``` ```bash theme={null} 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. 1. Ouvrez [HyperDX](http://localhost:8080/) 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** Vue de recherche des traces

**Affichage du fuseau horaire** HyperDX affiche les horodatages dans le fuseau horaire local de votre navigateur. Les données de démonstration couvrent **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)**. Ce large intervalle de temps garantit que vous verrez les traces de démonstration où que vous soyez. Une fois les traces visibles, vous pouvez réduire l’intervalle à une période de 24 heures pour obtenir des visualisations plus claires.

## Tableaux de bord et visualisation

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 le fichier de configuration du tableau de bord. 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) Importer un tableau de bord

3. Téléversez le fichier `nodejs-traces-dashboard.json`, puis cliquez sur **Finish Import** Terminer l’import

Pour le jeu de données de démonstration, définissez l’intervalle de temps sur **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)** (à ajuster selon votre fuseau horaire local). Par défaut, aucun intervalle de temps ne sera défini pour le tableau de bord importé.

## Dépannage

### Les traces de démo n’apparaissent pas après envoi via curl

Si vous avez envoyé des traces via curl mais qu’elles n’apparaissent pas dans HyperDX, essayez de les renvoyer une seconde fois : ```bash theme={null} 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.

### Aucune trace n’apparaît dans HyperDX

**Vérifiez que les variables d’environnement sont bien définies :** ```bash theme={null} 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 :** ```bash theme={null} 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.

## Étapes suivantes

* Configurez des [alertes](/docs/fr/clickstack/features/alerts) 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é)

## Mise en production

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](/docs/fr/clickstack/ingesting-data/opentelemetry) pour les modèles de déploiement en production et des exemples de configuration du collecteur.