> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Supervisión de logs de Systemd con ClickStack
> Supervisión de logs de Systemd y Journald con ClickStack
export const TrackedLink = ({href, eventName, children, ...rest}) => {
const handleClick = () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
return
{children}
;
};
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
**Resumen**
Recopila 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
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](#demo-dataset).
##### 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
El OpenTelemetry Collector envía datos al endpoint OTLP de ClickStack, que requiere autenticación.
1. Abre HyperDX en la URL de tu instancia de ClickStack (p. ej., [http://localhost:8080](http://localhost:8080))
2. Crea una cuenta o inicia sesión si es necesario
3. Ve a **Team Settings → API Keys**
4. Copia tu **API key de ingesta**
5. Configúrala como variable de entorno:
```bash theme={null}
export CLICKSTACK_API_KEY=your-api-key-here
```
Asegúrate de que tu sistema use systemd y tenga logs del journal:
```bash theme={null}
# 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:
```bash theme={null}
sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal
sudo systemctl restart systemd-journald
```
Crea un archivo de configuración para OpenTelemetry Collector:
```yaml theme={null}
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
```
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](#journalctl-not-found) para obtener más información.
Este ejemplo muestra cómo implementar el OTel collector junto con ClickStack:
```yaml theme={null}
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:
```bash theme={null}
docker compose up -d
```
Una vez configurado, inicia sesión en HyperDX y verifica que los logs se estén enviando:
1. Ve a la Búsqueda view
2. Establece source en Logs
3. Filtra por `service.name:systemd-logs`
4. 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.
Descarga el archivo de log de ejemplo:
```bash theme={null}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/systemd/systemd-demo.log
```
Crea un archivo de configuración para la demo:
```bash theme={null}
cat > systemd-demo.yaml << 'EOF'
receivers:
filelog:
include:
- /tmp/systemd-demo/systemd-demo.log
start_at: beginning
operators:
- type: regex_parser
regex: '^(?P\S+) (?P\S+) (?P\S+?)(?:\[(?P\d+)\])?: (?P.*)$'
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
```
Inicia ClickStack con los logs de demostración:
```bash theme={null}
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.
Una vez que ClickStack esté en ejecución:
1. Abre [HyperDX](http://localhost:8080/) e inicia sesión en tu cuenta
2. Ve a la Búsqueda view y selecciona `Logs` como source
3. Establece el rango de tiempo en **2025-11-14 00:00:00 - 2025-11-17 00:00:00**
**Visualización de la zona horaria**
HyperDX 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
Para ayudarte a empezar a monitorizar los logs de systemd con ClickStack, proporcionamos visualizaciones esenciales para los datos del journal de systemd.
Descargar el archivo de configuración del dashboard.
1. Abre HyperDX y ve a la sección Dashboards
2. Haz clic en **Import Dashboard** en la esquina superior derecha, dentro del menú de puntos suspensivos
3. Sube el archivo `systemd-logs-dashboard.json` y haz clic en **Finish Import**
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).
## Solución de problemas
### No aparecen logs en HyperDX
Comprueba si los logs están llegando a ClickHouse:
```bash theme={null}
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:
```bash theme={null}
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:
1. **Instala el collector en el host**:
```bash theme={null}
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
```
2. **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](/docs/es/clickstack/features/alerts) para eventos críticos del sistema (fallos del servicio, errores de autenticación, cierres por OOM)
* Crea [dashboards](/docs/es/clickstack/features/dashboards/overview) 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](/docs/es/clickstack/ingesting-data/opentelemetry) para conocer los patrones de despliegue en producción.