ResumenRecopila y visualiza logs del journal de systemd en ClickStack mediante el journald receiver de OpenTelemetry Collector. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.
Integración con sistemas existentes
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
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
El receiver journald requiere el binario journalctl para leer los archivos del journal. La imagen oficial otel/opentelemetry-collector-contrib no incluye journalctl de forma predeterminada.Para implementaciones en contenedores, puedes instalar el collector directamente en el host o crear una imagen personalizada con utilidades de systemd. Consulta la sección de solución de problemas para obtener más información. 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
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 Search 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
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
La demo usa el receiver filelog con logs de texto en lugar de journald para evitar tener que usar journalctl en el contenedor.
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 Search view y selecciona
Logs como source
- Establece el rango de tiempo en 2025-11-14 00:00:00 - 2025-11-17 00:00:00
Visualización de la zona horariaHyperDX muestra los timestamps en la zona horaria local de tu navegador. Los datos de demostración abarcan 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC). El rango de tiempo amplio garantiza que verás los logs de demostración independientemente de tu ubicación.
Dashboards y visualización
la 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
Para el conjunto de datos de demostración, establece el intervalo de tiempo en 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC) (ajústalo según tu zona horaria local).
No aparecen logs en HyperDX
docker exec clickstack clickhouse-client --query "
SELECT COUNT(*) as log_count
FROM otel_logs
WHERE ServiceName = 'systemd-logs'
"
docker logs otel-collector | grep -i "error\|journald" | tail -20
error: no se encontró journalctl
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
- 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
Esta guía utiliza un OpenTelemetry Collector independiente para leer los logs de systemd y enviarlos al endpoint de OTLP de ClickStack, que es el patrón recomendado para producción.
Para entornos de producción con varios hosts, ten en cuenta lo siguiente:
- Implementar el OpenTelemetry Collector como un conjunto de daemon en Kubernetes
- Ejecutar el OpenTelemetry Collector como un servicio de systemd en cada host
- Usar OpenTelemetry Operator para automatizar el despliegue
Consulta Ingesta con OpenTelemetry para ver patrones de despliegue para producción.
