Monitoreo de trazas de Node.js con ClickStack

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.

• 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

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.

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

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

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

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:

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.

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

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

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

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.

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 rango temporal en 2025-10-25 13:00:00 - 2025-10-28 13:00:00

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

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

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

El dashboard se creará con todas las visualizaciones ya preconfiguradas

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.

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.

• 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)

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