Monitorización de trazas de Nginx con ClickStack

Monitorización de trazas de Nginx con ClickStack

En resumen

Captura trazas distribuidas de Nginx en ClickStack con el módulo OpenTelemetry para Nginx. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.

​

Integración con una instalación existente de Nginx

Esta sección explica cómo añadir tracing distribuido a tu instalación existente de Nginx instalando el módulo de OpenTelemetry y configurándolo para enviar trazas a ClickStack. Si quieres probar la integración antes de configurar tu propio entorno, puedes hacerlo con nuestra configuración preconfigurada y datos de ejemplo en la siguiente sección.

Requisitos previos

• Instancia de ClickStack en ejecución con endpoints OTLP accesibles (puertos 4317/4318)
• Instalación existente de Nginx (versión 1.18 o superior)
• Acceso root o sudo para modificar la configuración de Nginx
• Nombre de host o dirección IP de la instancia de ClickStack

1. ​

   Instalar el módulo OpenTelemetry para Nginx

   La forma más sencilla de añadir tracing a Nginx es usar la imagen oficial de Nginx con soporte integrado para OpenTelemetry.

   Usar la imagen nginx:otel

   Sustituye tu imagen actual de Nginx por la versión con OpenTelemetry habilitado:

   # En tu docker-compose.yml o Dockerfile
   image: nginx:1.27-otel
   

   Esta imagen incluye ngx_otel_module.so preinstalado y listo para usar.

   Si ejecutas Nginx fuera de Docker, consulta la documentación de OpenTelemetry para Nginx para ver las instrucciones de instalación manual.

2. ​

   Configurar Nginx para enviar trazas a ClickStack

   Añade la configuración de OpenTelemetry a tu archivo nginx.conf. Esta configuración carga el módulo y envía las trazas al endpoint OTLP de ClickStack.

   Primero, obtén tu API key:

   1. Abre HyperDX en la URL de tu ClickStack
   2. Ve a Settings → API Keys
   3. Copia tu API key de ingesta
   4. Defínela como variable de entorno: export CLICKSTACK_API_KEY=your-api-key-here

   Añade esto a tu nginx.conf:

   load_module modules/ngx_otel_module.so;
   
   events {
       worker_connections 1024;
   }
   
   http {
       # Configuración del exporter de OpenTelemetry
       otel_exporter {
           endpoint <clickstack-host>:4317;
           header authorization ${CLICKSTACK_API_KEY};
       }
       
       # Nombre del servicio para identificar esta instancia de nginx
       otel_service_name "nginx-proxy";
       
       # Habilitar tracing
       otel_trace on;
       
       server {
           listen 80;
           
           location / {
               # Habilitar tracing para esta ubicación
               otel_trace_context propagate;
               otel_span_name "$request_method $uri";
               
               # Añadir detalles de la solicitud a las trazas
               otel_span_attr http.status_code $status;
               otel_span_attr http.request.method $request_method;
               otel_span_attr http.route $uri;
               
               # Tu configuración existente de proxy o aplicación
               proxy_pass http://your-backend;
           }
       }
   }
   

   Si ejecutas Nginx en Docker, pasa la variable de entorno al contenedor:

   services:
     nginx:
       image: nginx:1.27-otel
       environment:
         - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
       volumes:
         - ./nginx.conf:/etc/nginx/nginx.conf:ro
   

   Sustituye <clickstack-host> por el nombre de host o la dirección IP de tu instancia de ClickStack.

   • El puerto 4317 es el endpoint gRPC que utiliza el módulo de Nginx
   • otel_service_name debe describir claramente tu instancia de Nginx (por ejemplo, “api-gateway” o “frontend-proxy”)
   • Cambia otel_service_name para que coincida con tu entorno y sea más fácil identificarlo en HyperDX

   Comprender la configuración

   Qué se traza: Cada solicitud a Nginx crea un trace span que muestra:

   • Método y ruta de la solicitud
   • Código de estado HTTP
   • Duración de la solicitud
   • Marca de tiempo

   Atributos del span: Las directivas otel_span_attr añaden metadatos a cada trace, lo que te permite filtrar y analizar solicitudes en HyperDX por código de estado, método, ruta, etc.

   Después de realizar estos cambios, prueba tu configuración de Nginx:

   nginx -t
   

   Si la prueba es correcta, recarga Nginx:

   # Para Docker
   docker-compose restart nginx
   
   # Para systemd
   sudo systemctl reload nginx
   
3. ​

   Verificar las trazas en HyperDX

   Una vez configurado, inicia sesión en HyperDX y verifica que las trazas estén llegando. Deberías ver algo como esto. Si no ves trazas, intenta ajustar el rango de tiempo:

​

Conjunto de datos de demostración

Para los usuarios que quieran probar la integración de trazas de nginx antes de configurar sus sistemas de producción, proporcionamos un conjunto de datos de ejemplo con Nginx Traces pregeneradas y patrones de tráfico realistas.

1. ​

   Inicia ClickStack

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

   docker run --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

   Espera unos 30 segundos a que ClickStack se inicialice por completo antes de continuar.

   • Puerto 8080: interfaz web de HyperDX
   • Puerto 4317: endpoint OTLP gRPC (utilizado por el módulo de nginx)
   • Puerto 4318: endpoint OTLP HTTP (utilizado para las trazas de demostración)
2. ​

   Descarga el conjunto de datos de ejemplo

   Descarga el archivo de trazas de ejemplo y actualiza las marcas de tiempo a la hora actual:

   # Descargar las trazas
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json
   

   El conjunto de datos incluye:

   • 1.000 trace spans con temporización realista
   • 9 endpoints diferentes con patrones de tráfico variados
   • ~93 % de tasa de éxito (200), ~3 % de errores de cliente (404) y ~4 % de errores del servidor (500)
   • Latencias de entre 10 ms y 800 ms
   • Patrones de tráfico originales conservados y desplazados al momento actual
3. ​

   Envía trazas a ClickStack

   Establece tu API key como variable de entorno (si aún no la has configurado):

   export CLICKSTACK_API_KEY=your-api-key-here
   

   Obtén tu API key:

   1. Abre HyperDX en la URL de tu ClickStack
   2. Ve a Settings → API Keys
   3. Copia tu API key de ingesta

   Luego, envía las trazas a ClickStack:

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

   En ejecución en localhost

   Esta demostración asume que ClickStack se está ejecutando localmente en localhost:4318. Para instancias remotas, sustituye localhost por el hostname de tu ClickStack.

   Deberías ver una respuesta como {"partialSuccess":{}}, lo que indica que las trazas se enviaron correctamente. Las 1.000 trazas se ingestarán en ClickStack.

4. ​

   Verifica 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 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

   Esto es lo que deberías ver en la vista de búsqueda:

   Visualización de la zona horaria

   HyperDX muestra las marcas de tiempo 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 intervalo de tiempo amplio garantiza que verás las trazas de demostración independientemente de tu ubicación. Una vez que las veas, puedes reducir el intervalo a un período de 24 horas para obtener visualizaciones más claras.

​

Dashboards y visualización

Para ayudarte a empezar a monitorizar trazas con ClickStack, proporcionamos visualizaciones esenciales para los datos 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, en el menú de puntos suspensivos.

   3. Sube el archivo nginx-trace-dashboard.json y haz clic en “Finish Import”.
3. ​

   El dashboard se creará con todas las visualizaciones ya configuradas.

   Para el demo dataset, establece el rango de tiempo en 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) (ajústalo según tu zona horaria local). Por defecto, el dashboard importado no tendrá ningún rango de tiempo especificado.

​

Solución de problemas

​

No se muestran trazas en HyperDX

Verifique que el módulo de nginx esté cargado:

nginx -V 2>&1 | grep otel

Deberías ver referencias al módulo de OpenTelemetry.

Comprueba la conexión de red:

telnet <clickstack-host> 4317

Esto debería conectarse correctamente al endpoint de OTLP gRPC.

Verifique que la API key esté configurada:

echo $CLICKSTACK_API_KEY

Debería mostrar tu API key (no vacía).

Revisa los logs de errores de nginx:

# Para Docker
docker logs <nginx-container> 2>&1 | grep -i otel

# Para systemd
sudo tail -f /var/log/nginx/error.log | grep -i otel

Busque errores relacionados con OpenTelemetry.

Verifique que nginx esté recibiendo solicitudes:

# Verificar los logs de acceso para confirmar el tráfico
tail -f /var/log/nginx/access.log

​

Próximos pasos

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

​

Paso a producción

Esta guía envía trazas directamente desde el módulo de OpenTelemetry de Nginx al endpoint OTLP de ClickStack. Para implementaciones en producción, recomendamos ejecutar tu propio OTel collector como gateway para proporcionar procesamiento por lotes y resiliencia. Consulta Envío de datos de OpenTelemetry para la configuración de producción.