Supervisión de logs del host con ClickStack

Integración con hosts existentes

En esta sección se explica cómo configurar sus hosts existentes para que envíen logs del sistema a ClickStack modificando la configuración del ClickStack OTel collector para que lea todos los archivos de logs del sistema (syslog, auth, kernel, daemon y logs de aplicaciones).

Si desea probar la integración de logs del host antes de configurar su propio entorno existente, puede hacerlo con nuestra configuración preconfigurada y datos de ejemplo en la sección "conjunto de datos de demostración".

Requisitos previos

Instancia de ClickStack en ejecución
Sistema con archivos syslog
Acceso para modificar los archivos de configuración de ClickStack

Verifique que existan archivos de syslog

Primero, verifique que su sistema esté generando archivos de syslog:

# Check if syslog files exist (Linux)
ls -la /var/log/syslog /var/log/messages

# Or on macOS
ls -la /var/log/system.log

# View recent entries
tail -20 /var/log/syslog

Ubicaciones habituales de syslog:

Ubuntu/Debian: /var/log/syslog
RHEL/CentOS/Fedora: /var/log/messages
macOS: /var/log/system.log

Crear una configuración personalizada del OTel collector

ClickStack permite extender la configuración base del OpenTelemetry Collector montando un archivo de configuración personalizado y estableciendo una variable de entorno.

Cree un archivo llamado host-logs-monitoring.yaml con la configuración de su sistema:

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

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

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/messages
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

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

receivers:
  filelog/syslog:
    include:
      - /var/log/system.log
      - /host/private/var/log/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

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

Todas las configuraciones:

Leer archivos de syslog desde sus ubicaciones estándar
Analiza el formato syslog para extraer campos estructurados (timestamp, hostname, unidad/servicio, PID, mensaje)
Conservar las marcas de tiempo originales de los logs
Agregue el atributo source: host-logs para poder filtrar en HyperDX
Enrutar los logs al exportador de ClickHouse mediante un pipeline dedicado

Configurar 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 personalizado en /etc/otelcol-contrib/custom.config.yaml
Definir la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar el directorio de syslog para que el collector pueda leerlo

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:
      - ./host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log:/var/log:ro
      # ... other volumes ...

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

Si usas 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)/host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log:/var/log:ro \
  clickhouse/clickstack-all-in-one:latest

Verificar los logs en HyperDX

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

Ve a la vista de Búsqueda
Establece la fuente en Logs
Filtra por source:host-logs para ver logs específicos del host
Deberías ver entradas de log estructuradas con campos como unit, hostname, pid, message, etc.

Conjunto de datos de demostración

Para los usuarios que quieran probar la integración de logs del host antes de configurar sus sistemas de producción, proporcionamos un conjunto de datos de ejemplo con logs del sistema pregenerados y patrones realistas.

Descargar el conjunto de datos de ejemplo

Descargue el archivo de log de ejemplo:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

El conjunto de datos incluye:

Secuencia de arranque del sistema
Actividad de inicio de sesión por SSH (intentos exitosos y fallidos)
Incidente de seguridad (ataque de fuerza bruta con respuesta de fail2ban)
Mantenimiento programado (trabajos de cron, anacron)
Reinicios de servicios (rsyslog)
Mensajes del kernel y actividad del firewall
Una combinación de operaciones normales y eventos destacados

Crear la configuración de prueba del collector

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

cat > host-logs-demo.yaml << 'EOF'
receivers:
  filelog/journal:
    include:
      - /tmp/host-demo/journal.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      
      - type: add
        field: attributes.source
        value: "host-demo"
      
      - type: add
        field: resource["service.name"]
        value: "host-demo"

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

Ejecutar ClickStack con la configuración de demostración

Ejecute ClickStack con los logs de demostración y esta configuració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)/host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.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 vista de Búsqueda y establezca la fuente en Logs
Establezca el intervalo de tiempo en 2025-11-10 00:00:00 - 2025-11-13 00:00:00

Dashboards y visualización

Para ayudarte a empezar a monitorizar los logs del host con ClickStack, proporcionamos visualizaciones esenciales para los logs del sistema.

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importar 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 puntos suspensivos

Carga el archivo host-logs-dashboard.json y haz clic en Finish Import

Ver el dashboard

El dashboard se creará con todas las visualizaciones preconfiguradas:

Las visualizaciones clave incluyen:

Volumen de logs a lo largo del tiempo por nivel de severidad
Principales unidades de systemd que generan logs
Actividad de inicio de sesión por SSH (exitosos frente a fallidos)
Actividad del firewall (bloqueado frente a permitido)
Eventos de seguridad (inicios de sesión fallidos, vetos y bloqueos)
Actividad de reinicio de servicios

Solución de problemas

La configuración personalizada no se carga

Verifique que la variable de entorno esté configurada:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Verifica que el archivo de configuración personalizado esté montado y sea legible:

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

No aparecen logs en HyperDX

Verifique que los archivos de syslog existan y que se estén escribiendo correctamente:

# Comprobar si syslog existe
ls -la /var/log/syslog /var/log/messages

# Verificar que los logs se están escribiendo
tail -f /var/log/syslog

Verifique que el collector pueda leer los logs:

docker exec <container> cat /var/log/syslog | head -20

Comprueba que la configuración efectiva incluya el receiver filelog:

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

Revise si hay errores en los logs del collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i "filelog\|syslog"

Si usa el conjunto de datos de demostración, verifique que el archivo de log sea accesible:

docker exec <container> cat /tmp/host-demo/journal.log | wc -l

Los logs no se interpretan correctamente

Verifica que el formato de syslog coincida con la configuración que elegiste:

Para Linux moderno (Ubuntu 24.04+):

# Debe mostrarse en formato ISO8601: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Para versiones antiguas de Linux o macOS:

# Debe mostrar el formato tradicional: Nov 17 14:16:16
tail -5 /var/log/syslog
# o
tail -5 /var/log/system.log

Si el formato no coincide, selecciona la pestaña de configuración adecuada en la sección Crear una configuración personalizada del OTel collector.

Siguientes pasos

Configura alertas para eventos críticos del sistema (fallos de servicio, fallos de autenticación, advertencias de disco)
Filtra por unidades específicas para supervisar servicios concretos
Correlaciona los logs del host con los logs de la aplicación para una resolución de problemas más completa
Crea dashboards personalizados para la supervisión de seguridad (intentos de SSH, uso de sudo, bloqueos del firewall)

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 su propio OTel Collector y enviar los datos al endpoint OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para la configuración de producción.