Supervisión de logs de Systemd con ClickStack

Integración con sistemas existentes

Supervise los logs de journald de su sistema Linux ejecutando el OpenTelemetry Collector con el receiver journald para recopilar los logs del sistema y enviarlos a ClickStack a través de OTLP.

Si quiere probar primero esta integración sin modificar su configuración actual, vaya a la sección del conjunto de datos de demostración.

Requisitos previos

Instancia de ClickStack en ejecución
Sistema Linux con systemd (Ubuntu 16.04+, CentOS 7+, Debian 8+)
Docker o Docker Compose instalados en el sistema supervisado

Obtén la API key de ClickStack

El OpenTelemetry Collector envía datos al endpoint OTLP de ClickStack, que requiere autenticación.

Abre HyperDX en la URL de tu instancia de ClickStack (p. ej., http://localhost:8080)
Crea una cuenta o inicia sesión si es necesario
Ve a Team Settings → API Keys
Copia tu API key de ingesta

Configúrala como variable de entorno:

export CLICKSTACK_API_KEY=your-api-key-here

Verifica que el journal de systemd esté en ejecución

Asegúrate de que tu sistema use systemd y tenga logs del journal:

# Comprobar la versión de systemd
systemctl --version

# Ver entradas recientes del journal
journalctl -n 20

# Comprobar el uso de disco del journal
journalctl --disk-usage

Si el almacenamiento del journal está solo en memoria, habilita el almacenamiento persistente:

sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal
sudo systemctl restart systemd-journald

Crea la configuración de OpenTelemetry Collector

Crea un archivo de configuración para OpenTelemetry Collector:

cat > otel-config.yaml << 'EOF'
receivers:
  journald:
    directory: /var/log/journal
    priority: info
    units:
      - sshd
      - nginx
      - docker
      - containerd
      - systemd

processors:
  batch:
    timeout: 10s
    send_batch_size: 10000
  
  resource:
    attributes:
      - key: service.name
        value: systemd-logs
        action: insert
      - key: host.name
        from_attribute: _HOSTNAME
        action: upsert
  
  attributes:
    actions:
      - key: unit
        from_attribute: _SYSTEMD_UNIT
        action: upsert
      - key: priority
        from_attribute: PRIORITY
        action: upsert

exporters:
  otlphttp:
    endpoint: ${CLICKSTACK_ENDPOINT}
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [journald]
      processors: [resource, attributes, batch]
      exporters: [otlphttp]
EOF

Implementa con Docker Compose

Este ejemplo muestra cómo implementar el OTel collector junto con ClickStack:

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring
  
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.115.1
    depends_on:
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
      - CLICKSTACK_ENDPOINT=http://clickstack:4318
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
      - /var/log/journal:/var/log/journal:ro
      - /run/log/journal:/run/log/journal:ro
      - /etc/machine-id:/etc/machine-id:ro
    command: ["--config=/etc/otelcol/config.yaml"]
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Inicia los servicios:

docker compose up -d

Verifica los logs en HyperDX

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

Ve a la Búsqueda view
Establece source en Logs
Filtra por service.name:systemd-logs
Deberías ver entradas de log estructuradas con campos como unit, priority, MESSAGE, _HOSTNAME

Conjunto de datos de demostración

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

Descargar el conjunto de datos de ejemplo

Descarga el archivo de log de ejemplo:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/systemd/systemd-demo.log

Crear la configuración del collector de demostración

Crea un archivo de configuración para la demo:

cat > systemd-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/systemd-demo/systemd-demo.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: "systemd-demo"

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

Ejecutar ClickStack con datos de demostración

Inicia ClickStack con los logs de demostración:

docker run -d --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)/systemd-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/systemd-demo.log:/tmp/systemd-demo/systemd-demo.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verificar los logs en HyperDX

Una vez que ClickStack esté en ejecución:

Abre HyperDX e inicia sesión en tu cuenta
Ve a la Búsqueda view y selecciona Logs como source
Establece el rango de tiempo en 2025-11-14 00:00:00 - 2025-11-17 00:00:00

Dashboards y visualización

Para ayudarte a empezar a monitorizar los logs de systemd con ClickStack, proporcionamos visualizaciones esenciales para los datos del journal de systemd.

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, dentro del menú de puntos suspensivos

Sube el archivo systemd-logs-dashboard.json y haz clic en Finish Import

Ver el dashboard

El dashboard incluye visualizaciones de:

Volumen de logs a lo largo del tiempo
Principales unidades de systemd por cantidad de logs
Eventos de autenticación SSH
Fallos de servicios
Tasas de error

Solución de problemas

No aparecen logs en HyperDX

Comprueba si los logs están llegando a ClickHouse:

docker exec clickstack clickhouse-client --query "
SELECT COUNT(*) as log_count
FROM otel_logs
WHERE ServiceName = 'systemd-logs'
"

Si no hay resultados, revise los logs del collector:

docker logs otel-collector | grep -i "error\|journald" | tail -20

error: no se encontró journalctl

Si ves exec: "journalctl": executable file not found in $PATH:

La imagen otel/opentelemetry-collector-contrib no incluye journalctl. Puedes hacer una de estas dos cosas:

Instala el collector en el host:

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.115.0/otelcol-contrib_0.115.0_linux_amd64.tar.gz
tar -xzf otelcol-contrib_0.115.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/
otelcol-contrib --config=otel-config.yaml

Usa el enfoque de exportación de texto (como en la demo) con el receiver filelog para leer exportaciones de journald

Próximos pasos

Configura alertas para eventos críticos del sistema (fallos del servicio, errores de autenticación, cierres por OOM)
Crea dashboards adicionales para casos de uso concretos (monitorización de la seguridad de SSH, estado del servicio)
Filtra por unidades específicas de systemd para reducir el ruido y centrarte en los servicios que más importan

Llevar a producción

Esta guía usa un OpenTelemetry Collector independiente para leer logs de systemd y enviarlos al endpoint OTLP de ClickStack, que es el enfoque recomendado para producción.

Para entornos de producción con varios hosts, considera:

Desplegar el collector como un conjunto de daemon en Kubernetes
Ejecutar el collector como un servicio de systemd en cada host
Usar el OpenTelemetry Operator para el despliegue automatizado

Consulta Ingesta con OpenTelemetry para conocer los patrones de despliegue en producción.