Demo de HackerNews Analyzer

En resumenClone HackerNews Analyzer, complete .env con el endpoint y el token de OTLP, y luego pegue el prompt del agente. El backend no necesita importaciones de OpenTelemetry; el agente configura @hyperdx/node-opentelemetry al iniciar el proceso.Tiempo necesario: unos 10 minutos

HackerNews Analyzer es una aplicación de Node.js que consulta el conjunto de datos de HackerNews alojado en la demo pública de ClickHouse. Cada gráfico, tabla y cuadro de búsqueda ejecuta una consulta real de ClickHouse, por lo que cada interacción genera una traza cuyo span principal es la llamada HTTPS del backend a ClickHouse. Se trata de un caso distinto de la demo de reproducción de sesiones, que instrumenta una aplicación que se ejecuta únicamente en el navegador con ClickStack local mediante Docker. Aquí obtiene autoinstrumentación del backend, spans de consultas de ClickHouse y reproducción de sesiones desde la misma aplicación.

Requisitos previos

Node 18+ y npm
Un endpoint OTLP/HTTP de ClickStack y un token de ingestión:
- ClickHouse Cloud: abra el servicio y luego vaya a ClickStack → Configure su exporter de OpenTelemetry → Variables de entorno. El protocolo es http/protobuf. El header es authorization=<ingestion token>, sin el prefijo Bearer.
- Collector local: use http://localhost:4318. Si el collector no está protegido, deje authorization= vacío.

Clona el repositorio

Clona HackerNews Analyzer, instala las dependencias y copia la plantilla de variables de entorno:

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

Completarás el archivo .env en los siguientes pasos y, después, instrumentarás la aplicación desde este directorio.

Instrumentar la aplicación

Ejecute la aplicación

Desde el directorio clonado hn-news-analyzer, inicia la aplicación. La fuente de datos de ClickHouse usa de forma predeterminada el clúster de demostración público de solo lectura, por lo que se ejecuta sin configuración adicional:

./run.sh

Abra http://localhost:5001. Verá un selector de año, estadísticas resumidas, un gráfico de actividad, tablas con los principales usuarios y dominios, y un cuadro de búsqueda. Explore la aplicación: cambie de año y consulte las historias en detalle.

La aplicación HackerNews Analyzer ejecutándose localmente

En este punto, la aplicación está en ejecución, pero no está instrumentada. ClickStack no muestra datos: está a la espera de telemetría.

Configurar el entorno

Los SDKs leen las variables estándar del exporter de OpenTelemetry. No están codificadas de forma fija en el código fuente. Abra .env y configure:

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 es el endpoint OTLP/HTTP (puerto 4318). OTEL_EXPORTER_OTLP_HEADERS es el encabezado de autorización, con el formato authorization=<token> y sin prefijo Bearer.Si el collector no exige autenticación, deje el token vacío (OTEL_EXPORTER_OTLP_HEADERS=authorization=). La variable debe seguir presente; el SDK omite la inicialización si no está definida o está completamente vacía.El SDK para navegador reutiliza estos mismos valores. vite.config.ts incorpora el endpoint y el token en el paquete público durante la compilación, así que use un token de ingestión desechable, no uno de producción.

## Instrumente la aplicación

Elige una opción. Las tres llevan a la misma aplicación instrumentada.

Instrumentación con un agente
Instrumentación manual
Usa una rama preinstrumentada

Con el repositorio clonado y .env completado, pega esta instrucción en un agente de programación desde ese directorio para instrumentar la aplicación.

La instrumentación consta de tres partes: instalar los SDK, cambiar el comando de inicio y habilitar el SDK para navegador. Nada de esto modifica la lógica de negocio de la aplicación.

Instala el SDK de Node

npm install @hyperdx/node-opentelemetry

Habilita el envoltorio en run.sh

Al final de run.sh hay dos líneas exec. Comenta la línea de node sin instrumentación y descomenta la instrumentada:

 # ANTES: node sin instrumentación:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # DESPUÉS: mismo código fuente, envuelto por opentelemetry-instrument:
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js

Sigue iniciando la aplicación mediante scripts/entrypoint.js. Este shim llama a require('console') para que la captura de consola envuelva console.log. Si apuntas opentelemetry-instrument directamente a dist/server/index.js, se enviarán traces, pero los logs se descartarán silenciosamente.

Habilita el SDK para navegador

npm install @hyperdx/browser

En src/web/telemetry.ts, descomenta la importación, el bloque HyperDX.init({...}) y HyperDX.addAction en 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__ y __OTLP_AUTH_TOKEN__ son constantes de tiempo de compilación que vite.config.ts inyecta a partir de los mismos valores OTEL_EXPORTER_OTLP_* que usa el backend.

El token de ingestión se incluye en el paquete público del navegador y cualquiera que inspeccione la pestaña Network puede leerlo. Usa un token desechable.

Para omitir la instrumentación y empezar con una aplicación ya instrumentada, cambia a la rama instrumented.

git checkout instrumented
npm install

No ejecutes ./reset.sh en esta rama a menos que quieras eliminar los SDK.

Genere tráfico y consulte los datos de telemetría

Reinicie la aplicación para que se apliquen el nuevo comando de inicio y el paquete del navegador recién compilado:

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

Confirme que el banner de inicio muestre tres líneas “Health check passed” para /v1/traces, /v1/metrics y /v1/logs. Recargue la pestaña del navegador para que Vite sirva el paquete actualizado; después, cambie de año y abra historias para generar tráfico.Abra la UI de ClickStack:

Vaya a Búsqueda y filtre por los últimos 5 minutos. Los logs de hn-analyzer-api comenzarán a llegar.

Búsqueda de ClickStack que muestra logs de hn-analyzer-api de los últimos cinco minutos

Haga clic en una solicitud y recorra el trace hacia arriba. Verá el span del handler de Express, un span HTTP hijo que apunta a sql-clickhouse.clickhouse.com con una duración de red real y registros de console.log correlacionados en el mismo trace.

Trace de ClickStack con un span de handler de Express y un span HTTP hijo hacia ClickHouse

Abra Session Replay para reproducir un video navegable de una sesión del navegador, sincronizado con la línea de tiempo del trace.

Reproducción de sesión de ClickStack sincronizada con la línea de tiempo del trace

Los logs, las métricas, los traces y las reproducciones de sesión llegan a la misma UI, comparten el mismo lenguaje de consulta y se correlacionan automáticamente.

Más información

HackerNews Analyzer: el repositorio de demostración que instrumenta esta guía.
reproducción de sesiones: descripción general de la funcionalidad, opciones de SDK y controles de privacidad.
reproducción de sesiones Demo: una demo autónoma con una instancia local de ClickStack.
Primeros pasos con ClickStack: despliegue de ClickStack e ingesta de tus primeros datos.
Todos los conjuntos de datos de ejemplo: otros conjuntos de datos de ejemplo y guías.

Primeros pasos

Funcionalidades

Gestionar ClickStack

Guías

Socios de integración

Requisitos previos

Clona el repositorio

Instrumentar la aplicación

Instala el SDK de Node

Habilita el envoltorio en run.sh

Habilita el SDK para navegador

Más información

​Requisitos previos

​Clona el repositorio

​Instrumentar la aplicación

​Instala el SDK de Node

​Habilita el envoltorio en run.sh

​Habilita el SDK para navegador

​Más información

Requisitos previos

Clona el repositorio

Instrumentar la aplicación

Instala el SDK de Node

Habilita el envoltorio en run.sh

Habilita el SDK para navegador

Más información