Monitorización de logs de Nginx con ClickStack

En resumenRecopila y visualiza los logs de acceso de Nginx (formato JSON) en ClickStack usando el receiver filelog de OTel. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.

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

En la configuración personalizada, solo defines nuevos receiver y canalizaciones
Los processors (memory_limiter, transform, batch) y exporters (clickhouse) ya están definidos en la configuración base de ClickStack; solo tienes que referenciarlos por nombre
El operador time_parser extrae las marcas de tiempo del campo time_local de Nginx para conservar la hora original de los logs
Las canalizaciones envían los datos desde tus receiver al exporter de ClickHouse a través de los processors existentes

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:
    # ... configuración existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... otras variables de entorno ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... otros volúmenes ...

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

Asegúrese de que el colector de ClickStack tenga los permisos adecuados para leer los archivos de registro de nginx. En producción, use montajes de solo lectura (:ro) y siga el principio de mínimo privilegio.

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:

Visualización de la zona horariaHyperDX muestra los timestamps en la zona horaria local de su navegador. Los datos de demostración abarcan de 2025-10-20 11:00:00 a 2025-10-21 11:00:00 UTC. El amplio intervalo de tiempo garantiza que verá los logs de demostración independientemente de su ubicación. Una vez que vea los logs, puede 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 nginx con ClickStack, proporcionamos visualizaciones esenciales para los logs de Nginx.

la 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

Para el conjunto de datos de demostración, establece el intervalo de tiempo en 2025-10-20 11:00:00 - 2025-10-21 11: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.

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.

​Integración con una instalación existente de Nginx

Requisitos previos

​Configurar el log format de Nginx

​Crear una configuración personalizada del OTel collector

​Configura ClickStack para cargar una configuración personalizada

Opción 1: Docker Compose

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

​Verificar logs en HyperDX

​Conjunto de datos de demostración

​Descargar el conjunto de datos de ejemplo

​Crear la configuración de prueba del collector

​Ejecutar ClickStack con la configuración de demostración

​Verificar los logs en HyperDX

​Dashboards y visualización

​ la configuración del dashboard

​Importa el dashboard preconfigurado

​El dashboard se creará con todas las visualizaciones preconfiguradas

​Resolución de problemas

​La configuración personalizada no carga

​No aparecen logs en HyperDX

​Siguientes pasos

​Paso a producción

Integración con una instalación existente de Nginx

Configurar el log format de Nginx

Crear una configuración personalizada del OTel collector

Configura ClickStack para cargar una configuración personalizada

Verificar logs en HyperDX

Conjunto de datos de demostración

Descargar el conjunto de datos de ejemplo

Crear la configuración de prueba del collector

Ejecutar ClickStack con la configuración de demostración

Verificar los logs en HyperDX

Dashboards y visualización

la configuración del dashboard

Importa el dashboard preconfigurado

El dashboard se creará con todas las visualizaciones preconfiguradas

Resolución de problemas

La configuración personalizada no carga

No aparecen logs en HyperDX

Siguientes pasos

Paso a producción