Monitorización de logs de Nginx con ClickStack

Integración con una instalación existente de Nginx

En esta sección se explica cómo configurar una instalación existente de Nginx para enviar logs a ClickStack modificando la configuración del OTel collector de ClickStack. Si desea probar la integración antes de configurar su propio entorno existente, puede hacerlo con nuestra configuración predefinida y datos de muestra en la siguiente sección.

Requisitos previos

Una instancia de ClickStack en ejecución
Una instalación existente de Nginx
Acceso para modificar los archivos de configuración de Nginx

Configurar el log format de Nginx

Primero, configure Nginx para que genere logs en formato JSON y así facilitar el parsing. Añada esta definición de log format a su nginx.conf:

El archivo nginx.conf suele encontrarse en:

Linux (apt/yum): /etc/nginx/nginx.conf
macOS (Homebrew): /usr/local/etc/nginx/nginx.conf o /opt/homebrew/etc/nginx/nginx.conf
Docker: La configuración suele montarse como un volumen

Añada esta definición de log format al bloque http:

http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}

Después de realizar este cambio, vuelve a cargar Nginx.

Crear una configuración personalizada del OTel collector

ClickStack le permite ampliar la configuración base de OpenTelemetry Collector montando un archivo de configuración personalizado y definiendo una variable de entorno. La configuración personalizada se combina con la configuración base administrada por HyperDX mediante OpAMP.

Cree un archivo llamado nginx-monitoring.yaml con la siguiente configuración:

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Esta configuración:

Lee los logs de Nginx desde sus ubicaciones estándar
Analiza entradas de log en JSON
Extrae y conserva las marcas de tiempo originales de los logs
Añade el atributo source: Nginx para filtrar en HyperDX
Envía los logs al exporter de ClickHouse mediante una canalización dedicada

Configura ClickStack para cargar una configuración personalizada

Para habilitar una configuración personalizada del collector en tu despliegue actual de ClickStack, debes:

Montar el archivo de configuración personalizada en /etc/otelcol-contrib/custom.config.yaml
Establecer la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar los directorios de logs de Nginx para que el collector pueda leerlos

Opción 1: Docker Compose

Actualiza la configuración de despliegue de ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

Opción 2: Docker Run (imagen todo en uno)

Si utiliza la imagen todo en uno con docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest

Verificar logs en HyperDX

Una vez configurado, inicia sesión en HyperDX y verifica que se estén recibiendo logs:

Ve a la vista de búsqueda
Configura la fuente en Logs y comprueba que aparezcan entradas de registro con campos como request, request_time, upstream_response_time, etc.

Este es un ejemplo de lo que deberías ver:

Conjunto de datos de demostración

Para quienes quieran probar la integración de nginx antes de configurar sus sistemas de producción, proporcionamos un conjunto de datos de ejemplo con logs de acceso de nginx pregenerados y patrones de tráfico realistas.

Descargar el conjunto de datos de ejemplo

# Descargar los logs
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

El conjunto de datos incluye:

Entradas de log con patrones de tráfico realistas
Varios endpoints y métodos HTTP
Una combinación de solicitudes correctas y errores
Tiempos de respuesta y recuentos de bytes realistas

Crear la configuración de prueba del collector

Cree un archivo llamado nginx-demo.yaml con la siguiente configuración:

cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # Leer desde el principio para los datos de demostración
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

service:
  pipelines:
    logs/nginx-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Ejecutar ClickStack con la configuración de demostración

Ejecute ClickStack con los logs y la configuración de demostración:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verificar los logs en HyperDX

Una vez que ClickStack esté en ejecución:

Abra HyperDX e inicie sesión en su cuenta (puede que primero tenga que crear una cuenta)
Vaya a la Search view y establezca Logs como source
Establezca el intervalo de tiempo en 2025-10-19 11:00:00 - 2025-10-22 11:00:00

Esto es lo que debería ver en la Search view:

Dashboards y visualización

Para ayudarte a empezar a monitorizar nginx con ClickStack, proporcionamos visualizaciones esenciales para los logs de Nginx.

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importa el dashboard preconfigurado

Abre HyperDX y ve a la sección Dashboards.
Haz clic en "Import Dashboard" en la esquina superior derecha, en el menú de tres puntos.

Sube el archivo nginx-logs-dashboard.json y haz clic en "Finish import".

El dashboard se creará con todas las visualizaciones preconfiguradas

Resolución de problemas

La configuración personalizada no carga

Verifique que la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE esté configurada correctamente

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Compruebe que el archivo de configuración personalizado esté montado en /etc/otelcol-contrib/custom.config.yaml

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml

Vea el contenido de la configuración personalizada para comprobar que se puede leer

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

No aparecen logs en HyperDX

Asegúrate de que nginx esté escribiendo logs en formato JSON

tail -f /var/log/nginx/access.log

Verifique que el collector pueda leer los logs

docker exec `<container>` cat /var/log/nginx/access.log

Verifica que la configuración efectiva incluya el receiver filelog

docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog

Revise si hay errores en los logs del collector

docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

Siguientes 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 APIs, eventos de seguridad)

Paso a producción

Esta guía amplía el OpenTelemetry Collector integrado de ClickStack para facilitar una configuración rápida. Para implementaciones en producción, recomendamos ejecutar tu propio OTel Collector y enviar los datos al endpoint OTLP de ClickStack. Consulta Envío de datos de OpenTelemetry para ver la configuración de producción.