Démo HackerNews Analyzer

TL;DRClonez HackerNews Analyzer, renseignez .env avec votre endpoint OTLP et votre jeton, puis collez le prompt de l’agent. Le backend ne nécessite aucun import OpenTelemetry ; l’agent connecte @hyperdx/node-opentelemetry au démarrage du processus.Temps nécessaire : environ 10 minutes

HackerNews Analyzer est une application Node.js qui interroge le dataset HackerNews hébergé dans la démo publique de ClickHouse. Chaque graphique, table et champ de recherche correspond à une véritable requête ClickHouse, de sorte que chaque interaction produit une trace dont le span principal est l’appel HTTPS du backend vers ClickHouse. Cette tâche est différente de la démo de session replay, qui instrumente une application uniquement côté navigateur avec un ClickStack Docker local. Ici, vous bénéficiez de l’auto-instrumentation du backend, des spans de requêtes ClickHouse et du session replay dans la même application.

Prérequis

Node 18+ et npm
Un endpoint OTLP/HTTP ClickStack et un jeton d’ingestion :
- ClickHouse Cloud : ouvrez le service, puis ClickStack → Configure your OpenTelemetry exporter → Env vars. Le protocole est http/protobuf. Le header est authorization=<ingestion token>, sans préfixe Bearer.
- Collector local : utilisez http://localhost:4318. Si le collector n’est pas sécurisé, laissez authorization= vide.

Clonez le dépôt

Clonez HackerNews Analyzer, installez les dépendances et copiez le modèle de fichier d’environnement :

git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env

Vous renseignerez le fichier .env à l’étape suivante, puis instrumenterez l’application depuis ce répertoire.

Instrumenter l’application

Exécutez l’application

Depuis le répertoire hn-news-analyzer cloné, démarrez l’application. La source de données ClickHouse utilise par défaut le cluster de démonstration public en lecture seule. Aucune configuration supplémentaire n’est donc nécessaire :

./run.sh

Ouvrez http://localhost:5001. Vous verrez un sélecteur d’année, des statistiques récapitulatives, un graphique d’activité, des tableaux des principaux utilisateurs et domaines, ainsi qu’un champ de recherche. Explorez l’interface : changez d’année, consultez les articles en détail.

L’application HackerNews Analyzer exécutée localement

À ce stade, l’application s’exécute, mais n’est pas instrumentée. ClickStack n’affiche aucune donnée : il attend la télémétrie.

Configurer l’environnement

Les SDKs utilisent les variables standard de l’exporter OpenTelemetry. Elles ne sont pas codées en dur dans le code source. Ouvrez .env et définissez :

OTEL_SERVICE_NAME=hn-analyzer-api
OTEL_EXPORTER_OTLP_ENDPOINT=<your-otlp-http-endpoint>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

OTEL_EXPORTER_OTLP_ENDPOINT est l’endpoint OTLP/HTTP (port 4318). OTEL_EXPORTER_OTLP_HEADERS est l’en-tête d’autorisation, au format authorization=<token>, sans préfixe Bearer.Si le collector n’applique pas d’authentification, laissez le token vide (OTEL_EXPORTER_OTLP_HEADERS=authorization=). La variable doit néanmoins être présente : le SDK ignore l’initialisation si elle n’est pas définie ou si elle est entièrement vide.Le SDK pour navigateur réutilise ces mêmes valeurs. vite.config.ts intègre l’endpoint et le token au bundle public lors du build ; utilisez donc un token d’ingestion temporaire, et non un token de production.

Instrumenter l’application

Choisissez une méthode. Toutes trois aboutissent à la même application instrumentée.

Instrumentation avec un agent
Instrumentation manuelle
Utiliser une branche pré-instrumentée

Une fois le dépôt cloné et le fichier .env renseigné, collez ce prompt dans un agent de code depuis ce répertoire afin d’instrumenter l’application.

L’instrumentation comporte trois étapes : installer les SDKs, modifier la commande de lancement et activer le SDK navigateur. Aucune ne modifie la logique métier de l’application.

Installer le SDK Node

npm install @hyperdx/node-opentelemetry

Activer le wrapper dans run.sh

La fin de run.sh contient deux lignes exec. Commentez la ligne node standard et décommentez celle instrumentée :

 # AVANT : node standard, sans instrumentation :
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # APRÈS : même source, encapsulée par opentelemetry-instrument :
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js

Continuez à lancer l’application via scripts/entrypoint.js. Ce shim appelle require('console') afin que la capture de console encapsule console.log. Si vous pointez directement opentelemetry-instrument vers dist/server/index.js, les traces sont bien envoyées, mais les logs sont silencieusement ignorés.

Activer le SDK navigateur

npm install @hyperdx/browser

Dans src/web/telemetry.ts, décommentez l’import, le bloc HyperDX.init({...}) et HyperDX.addAction dans recordAction() :

-// import HyperDX from '@hyperdx/browser';
+import HyperDX from '@hyperdx/browser';

 export function initTelemetry(): void {
-  // HyperDX.init({
-  //   url: __OTLP_ENDPOINT__,
-  //   apiKey: __OTLP_AUTH_TOKEN__,
-  //   service: 'hn-analyzer-web',
-  //   tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
-  //   consoleCapture: true,
-  //   advancedNetworkCapture: true,
-  // });
+  HyperDX.init({
+    url: __OTLP_ENDPOINT__,
+    apiKey: __OTLP_AUTH_TOKEN__,
+    service: 'hn-analyzer-web',
+    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
+    consoleCapture: true,
+    advancedNetworkCapture: true,
+  });
 }

__OTLP_ENDPOINT__ et __OTLP_AUTH_TOKEN__ sont des constantes de compilation injectées par vite.config.ts à partir des mêmes valeurs OTEL_EXPORTER_OTLP_* que celles utilisées par le backend.

Le jeton d’ingestion est intégré au bundle navigateur public et peut être lu par toute personne inspectant l’onglet Network. Utilisez un jeton jetable.

Pour éviter l’instrumentation et démarrer avec une application déjà instrumentée, effectuez un checkout de la branche instrumented.

git checkout instrumented
npm install

N’exécutez pas ./reset.sh sur cette branche, sauf si vous souhaitez supprimer les SDKs.

Générez du trafic et consultez les données de télémétrie

Redémarrez l’application pour que la nouvelle commande de démarrage et le bundle du navigateur fraîchement compilé prennent effet :

# Ctrl-C the previous run, then:
./run.sh

Vérifiez que la bannière de démarrage affiche trois lignes « Health check passed » pour /v1/traces, /v1/metrics et /v1/logs. Rechargez l’onglet du navigateur pour que Vite serve le bundle mis à jour, puis changez d’année et cliquez sur des articles afin de générer du trafic.Ouvrez l’UI ClickStack :

Accédez à Search et filtrez sur les 5 dernières minutes. Les logs de hn-analyzer-api affluent.

Recherche ClickStack affichant les logs de hn-analyzer-api des cinq dernières minutes

Cliquez sur une requête et remontez la trace. Vous verrez le span du handler Express, un span HTTP enfant pointant vers sql-clickhouse.clickhouse.com avec une durée réseau réelle, ainsi que des enregistrements console.log corrélés dans la même trace.

Trace ClickStack avec un span de handler Express et un span HTTP enfant vers ClickHouse

Ouvrez Session Replay pour lire une vidéo d’une session de navigateur, dont vous pouvez parcourir la chronologie, synchronisée avec celle de la trace.

Replay de session ClickStack synchronisé avec la chronologie de la trace

Les logs, métriques, traces et replays de session sont regroupés dans la même UI, utilisent le même langage de requête et sont automatiquement corrélés.

En savoir plus

HackerNews Analyzer : le dépôt de démonstration instrumenté par ce guide.

Session Replay : vue d’ensemble de la fonctionnalité, options du SDK et paramètres de confidentialité.
Session Replay Demo : une démo autonome avec une instance locale de ClickStack.
ClickStack Prise en main : déployez ClickStack et ingérez vos premières données.
Tous les jeux de données d’exemple : d’autres jeux de données d’exemple et guides.

Premiers pas

Fonctionnalités

Gérer ClickStack

Guides

Partenaires d’intégration

Prérequis

Clonez le dépôt

Instrumenter l’application

Installer le SDK Node

Activer le wrapper dans run.sh

Activer le SDK navigateur

En savoir plus

​Prérequis

​Clonez le dépôt

​Instrumenter l’application

​Installer le SDK Node

​Activer le wrapper dans run.sh

​Activer le SDK navigateur

​En savoir plus

Prérequis

Clonez le dépôt

Instrumenter l’application

Installer le SDK Node

Activer le wrapper dans run.sh

Activer le SDK navigateur

En savoir plus