Instrumentar una aplicación con Managed ClickStack

Esta guía muestra cómo instrumentar una aplicación sencilla de Node.js con OpenTelemetry y enviar sus logs, métricas y trazas a Managed ClickStack. El backend se instrumenta sin necesidad de hacer cambios en el código fuente de la aplicación. HackerNews Analyzer es una pequeña aplicación de Node.js que consulta el conjunto de datos de HackerNews alojado en la instancia de demo pública de ClickHouse. Cada gráfico, tabla y cuadro de búsqueda está respaldado por 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.

Requisitos previos

Un OTel collector disponible y accesible, que ingiera datos en su servicio de Managed ClickStack. Necesita su endpoint de OTLP y un token de ingestión.
Node 18+ y npm.

Clona y ejecuta la aplicación

Clona el repositorio, instala las dependencias y crea el archivo .env:

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

La fuente de datos de ClickHouse usa de forma predeterminada el clúster demo público y de solo lectura, por lo que la aplicación funciona sin necesidad de configuración adicional. Iníciala:

./run.sh

Abre http://localhost:5001. Verás un selector de año, estadísticas resumidas, un gráfico de actividad, tablas de usuarios y dominios principales, y un cuadro de búsqueda. Explora la aplicación: cambia de año y profundiza en las historias.

La aplicación HackerNews Analyzer ejecutándose localmente

En este punto, la aplicación se está ejecutando, pero aún no está instrumentada. ClickStack no muestra datos: está esperando telemetría. Este es el estado “anterior”.

Obtén los detalles de conexión

La aplicación necesita dos valores para conectarse al colector:

OTEL_EXPORTER_OTLP_ENDPOINT: el endpoint de OTLP que expone tu colector (normalmente el puerto 4318 para OTLP sobre HTTP).
OTEL_EXPORTER_OTLP_HEADERS: el encabezado de autorización que contiene tu token de ingestión, con el formato authorization=<token>.

Abre .env y configúralos:

OTEL_SERVICE_NAME=hn-analyzer-api
OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-collector-endpoint>:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>

El SDK usa OTEL_EXPORTER_OTLP_HEADERS para establecer el encabezado de autorización para las tres señales: trazas, métricas y logs. Si el collector se ejecuta localmente y no exige autenticación, puedes dejar el valor vacío (OTEL_EXPORTER_OTLP_HEADERS=authorization=), pero la variable debe estar presente; el SDK omite por completo la inicialización si no está definida o si está completamente vacía.

Instrumentar la aplicación

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

Instalar los SDKs

Instala los SDKs de OpenTelemetry tanto para backend como para navegador:

npm install @hyperdx/node-opentelemetry @hyperdx/browser

Usa la CLI de opentelemetry-instrument

La aplicación se inicia con run.sh, que tiene dos líneas exec al final: una activa y otra comentada. Cambia cuál de ellas está activa para que Node se ejecute a través de opentelemetry-instrument:

 # BEFORE: plain node, no instrumentation, collector stays silent:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # AFTER: same source, wrapped by opentelemetry-instrument CLI.
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js

Ese es todo el cambio en el backend. La autoinstrumentación se carga mediante opentelemetry-instrument al iniciar el proceso.

Habilita el SDK para navegador

Para capturar trazas distribuidas (del navegador al backend) y repeticiones de sesión, habilita el SDK para navegador en src/web/telemetry.ts. Descomenta la importación y el bloque HyperDX.init({...}):

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

No se requiere editar .env adicionalmente. __OTLP_ENDPOINT__ y __OTLP_AUTH_TOKEN__ son constantes de tiempo de compilación inyectadas por vite.config.ts: el endpoint es OTEL_EXPORTER_OTLP_ENDPOINT y el token se obtiene de OTEL_EXPORTER_OTLP_HEADERS, los mismos valores que usa el backend.

El token de ingestión está integrado en el bundle público del navegador y cualquiera puede verlo al inspeccionar la pestaña Network.

Generar tráfico y ver la telemetría

Reinicia la aplicación para que el nuevo comando de inicio y el paquete del navegador recién compilado surtan efecto:

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

Recarga la pestaña del navegador para que Vite sirva el bundle actualizado; luego recarga la aplicación unas cuantas veces, cambia de año y haz clic en las historias para generar tráfico.Abre la UI de ClickStack:

Ve a Búsqueda y filtra por los últimos 5 minutos. Los logs de hn-analyzer-api empezarán a aparecer.

Haz clic en una petición y sube por la traza. Verás el span del handler de Express, un span HTTP hijo que apunta al clúster de ClickHouse con la duración real de la red, y registros de console.log correlacionados en la misma traza.

Abre Session Replay para reproducir un video de una sesión del navegador por el que puedes desplazarte, sincronizado con la cronología de la traza.

Los logs, las métricas, las trazas y las repeticiones de sesión aparecen en la misma UI, comparten el mismo lenguaje de consulta y se correlacionan automáticamente.

Más información

Session Replay: descripción general de la funcionalidad, opciones de SDK y controles de privacidad.
Session Replay 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

Características

Administración de ClickStack

Guías

Socios de integración

Instrumentar una aplicación con Managed ClickStack

Requisitos previos

Instalar los SDKs

Usa la CLI de opentelemetry-instrument

Habilita el SDK para navegador

Más información

​Requisitos previos

​Instalar los SDKs

​Usa la CLI de opentelemetry-instrument

​Habilita el SDK para navegador

​Más información

Requisitos previos

Instalar los SDKs

Usa la CLI de opentelemetry-instrument

Habilita el SDK para navegador

Más información