Monitorización de trazas de Nginx con ClickStack

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.

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.

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

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:

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)

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), ~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

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

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.

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 rango 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:

Descargar el archivo de configuración del dashboard.

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".