Monitoreo de trazas de Node.js con ClickStack

Monitoreo de trazas de aplicaciones Node.js con ClickStack

En resumen

Captura trazas distribuidas de aplicaciones Node.js en ClickStack con la instrumentación automática de OpenTelemetry. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.

​

Integración con una aplicación Node.js existente

En esta sección se explica cómo añadir trazado distribuido a su aplicación Node.js existente mediante la instrumentación automática de OpenTelemetry.

Si desea probar la integración antes de configurar su propio entorno, puede hacerlo con nuestra configuración predefinida y datos de muestra en la sección del conjunto de datos de demostración.

Requisitos previos

• Instancia de ClickStack en funcionamiento con endpoints OTLP accesibles (puertos 4317/4318)
• Aplicación de Node.js existente (Node.js 14 o superior)
• Gestor de paquetes npm o yarn
• hostname o dirección IP de ClickStack

1. ​

   Instala y configura OpenTelemetry

   Instala el paquete @hyperdx/node-opentelemetry e inicialízalo al comienzo de tu aplicación. Consulta la guía del SDK para Node.js para ver los pasos detallados de instalación.

2. ​

   Obtén la API key de ClickStack

   Necesitas una API key para enviar trazas al endpoint OTLP de ClickStack.

   1. Abre HyperDX en la URL de tu ClickStack (p. ej., http://localhost:8080)
   2. Crea una cuenta o inicia sesión si hace falta
   3. Ve a Configuración del equipo → API Keys
   4. Copia tu API key de ingesta
3. ​

   Ejecuta tu aplicación

   Inicia tu aplicación de Node.js con las variables de entorno configuradas:

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

   Genera algo de tráfico

   Haz solicitudes a tu aplicación para generar trazas:

   # Solicitudes simples
   curl http://localhost:3000/
   curl http://localhost:3000/api/users
   curl http://localhost:3000/api/products
   
   # Simular carga
   for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done
   
5. ​

   Verifica las trazas en HyperDX

   Una vez configurado, inicia sesión en HyperDX y verifica que las trazas se estén recibiendo. Deberías ver algo como esto. Si no ves trazas, prueba a ajustar el rango temporal:

   Haz clic en cualquier traza para ver la vista detallada con spans, duración y atributos:

​

Conjunto de datos de demostración

Para los usuarios que quieran probar el tracing de Node.js con ClickStack antes de instrumentar sus aplicaciones de producción, proporcionamos un conjunto de datos de ejemplo con trazas pregeneradas de aplicaciones Node.js con patrones de tráfico realistas.

1. ​

   Descargar el conjunto de datos de ejemplo

   Descarga el archivo de trazas de ejemplo:

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

   Iniciar ClickStack

   Si todavía no tienes ClickStack en ejecución, inícialo con:

   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
   
3. ​

   Obtener la API key de ClickStack

   Necesitas una API key para enviar trazas al endpoint OTLP de ClickStack.

   1. Abre HyperDX en la URL de tu instancia de ClickStack (p. ej., http://localhost:8080)
   2. Crea una cuenta o inicia sesión si es necesario
   3. Ve a Configuración del equipo → API Keys
   4. Copia tu API key de ingesta

   Define tu API key como una variable de entorno:

   export CLICKSTACK_API_KEY=your-api-key-here
   
4. ​

   Enviar las trazas a ClickStack

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

   Deberías ver una respuesta como {"partialSuccess":{}}, lo que indica que las trazas se enviaron correctamente.

5. ​

   Verificar las trazas en HyperDX

   1. Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una cuenta)
   2. Ve a la vista de Búsqueda y establece la fuente en Traces
   3. Establece el intervalo de tiempo en 2025-10-25 13:00:00 - 2025-10-28 13:00:00

   Visualización de la zona horaria

   HyperDX muestra los timestamps en la zona horaria local de tu navegador. Los datos de demostración abarcan 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC). El amplio intervalo de tiempo garantiza que verás las trazas de demostración independientemente de tu ubicación. Una vez que veas las trazas, puedes reducirlo a un período de 24 horas para obtener visualizaciones más claras.

​

Dashboards y visualización

Para ayudarte a empezar a monitorizar el rendimiento de aplicaciones Node.js, proporcionamos un dashboard preconfigurado con visualizaciones esenciales de trazas.

1. ​

   la configuración del dashboard

2. ​

   Importa el dashboard preconfigurado

   1. Abre HyperDX y ve a la sección Dashboards
   2. Haz clic en Import Dashboard en la esquina superior derecha (debajo del menú de tres puntos)

   3. Sube el archivo nodejs-traces-dashboard.json y haz clic en Finish Import
3. ​

   El dashboard se creará con todas las visualizaciones ya preconfiguradas

   Para el conjunto de datos de demostración, establece el intervalo de tiempo en 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) (ajústalo según tu zona horaria local). El dashboard importado no tendrá ningún intervalo de tiempo especificado de forma predeterminada.

​

Solución de problemas

​

Las trazas de demostración no aparecen con curl

Si has enviado trazas con curl pero no las ves en HyperDX, intenta enviarlas una segunda vez:

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

Este es un problema conocido que se produce al usar el método de demostración con curl y no afecta a las aplicaciones de producción instrumentadas.

​

No se muestran trazas en HyperDX

Verifique que las variables de entorno estén configuradas:

echo $CLICKSTACK_API_KEY
# Debería mostrar tu API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Debería mostrar http://localhost:4318 o el host de tu ClickStack

Compruebe la conectividad de red:

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

Debería conectarse correctamente al endpoint OTLP.

Comprueba los logs de la aplicación: Busca mensajes de inicialización de OpenTelemetry al iniciar la aplicación. El SDK de HyperDX debería mostrar una confirmación de que se ha inicializado.

​

Próximos pasos

• Configura alertas para métricas críticas (tasas de errores, umbrales de latencia)
• Crea dashboards adicionales para casos de uso específicos (monitorización de API, eventos de seguridad)

​

Pasar a producción

Esta guía utiliza el SDK de HyperDX, que envía trazas directamente al endpoint OTLP de ClickStack. Esto funciona bien para entornos de desarrollo, pruebas y despliegues de producción pequeños o medianos. Para entornos de producción más grandes, o si necesita un mayor control sobre los datos de telemetría, considere implementar su propio OpenTelemetry Collector como agente. Consulte Ingesta con OpenTelemetry para ver patrones de despliegue en producción y ejemplos de configuración del OpenTelemetry Collector.