Monitorando logs do Systemd com o ClickStack

Integração com sistemas existentes

Monitore os logs do journald do seu sistema Linux executando o OpenTelemetry Collector com o journald receiver para coletar logs do sistema e enviá-los ao ClickStack via OTLP.

Se quiser testar essa integração primeiro sem modificar seu ambiente atual, pule para a seção do dataset de demonstração.

Pré-requisitos

Instância do ClickStack em execução
Sistema Linux com systemd (Ubuntu 16.04+, CentOS 7+, Debian 8+)
Docker ou Docker Compose instalado no sistema monitorado

Obtenha a API key do ClickStack

O OpenTelemetry Collector envia dados para o endpoint OTLP do ClickStack, que exige autenticação.

Abra o HyperDX na URL do ClickStack (por exemplo, http://localhost:8080)
Crie uma conta ou faça login, se necessário
Vá para Team Settings → API Keys
Copie sua API key de ingestão

Defina-a como uma variável de ambiente:

export CLICKSTACK_API_KEY=your-api-key-here

Verifique se o journal do systemd está em execução

Verifique se o sistema usa systemd e se há logs no journal:

# Verifique a versão do systemd
systemctl --version

# Veja entradas recentes do journal
journalctl -n 20

# Verifique o uso de disco do journal
journalctl --disk-usage

Se o journal estiver armazenando dados apenas em memória, habilite o armazenamento persistente:

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

Crie a configuração do OpenTelemetry Collector

Crie um arquivo de configuração para o 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

Faça a implantação com Docker Compose

Este exemplo mostra a implantação do OTel collector junto com o 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

Inicie os serviços:

docker compose up -d

Verifique os logs no HyperDX

Depois da configuração, faça login no HyperDX e verifique se os logs estão chegando:

Vá para a visualização Busca
Defina a source como Logs
Filtre por service.name:systemd-logs
Você deverá ver entradas de log estruturadas com campos como unit, priority, MESSAGE, _HOSTNAME

Dataset de demonstração

Para usuários que querem testar a integração de logs do systemd antes de configurar seus sistemas de produção, fornecemos um conjunto de dados de exemplo com logs do systemd pré-gerados e padrões realistas.

Baixar o conjunto de dados de exemplo

Baixe o arquivo de log de exemplo:

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

Criar a configuração do collector de demonstração

Crie um arquivo de configuração para a demonstração:

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

Executar o ClickStack com dados de demonstração

Inicie o ClickStack com os logs de demonstração:

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 os logs no HyperDX

Quando o ClickStack estiver em execução:

Abra o HyperDX e entre na sua conta
Acesse a visualização Busca e defina a source como Logs
Defina o intervalo de tempo como 2025-11-14 00:00:00 - 2025-11-17 00:00:00

Dashboards e visualização

Para ajudar você a começar a monitorar logs do systemd com o ClickStack, fornecemos visualizações essenciais para os dados do journal do systemd.

Baixe a configuração do dashboard

Baixe o arquivo de configuração do dashboard.

Importe o dashboard pré-configurado

Abra o HyperDX e navegue até a seção Dashboards
Clique em Import Dashboard no canto superior direito, no menu de reticências

Faça upload do arquivo systemd-logs-dashboard.json e clique em Finish Import

Visualize o dashboard

O dashboard inclui visualizações para:

Volume de logs ao longo do tempo
Principais unidades do systemd por número de logs
Eventos de autenticação SSH
Falhas de serviço
Taxas de erro

Solução de problemas

Nenhum log aparece no HyperDX

Verifique se os logs estão chegando ao ClickHouse:

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

Se não houver resultados, verifique os logs do collector:

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

erro de `journalctl` não encontrado

Se você vir exec: "journalctl": executable file not found in $PATH:

A imagem otel/opentelemetry-collector-contrib não inclui o journalctl. Você pode:

Instalar o collector no 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

Use a abordagem de exportação em texto (como na demonstração) com o receiver filelog lendo as exportações do journald

Próximos passos

Configure alertas para eventos críticos do sistema (falhas de serviço, falhas de autenticação, encerramentos por OOM)
Crie dashboards adicionais para casos de uso específicos (monitoramento de segurança do SSH, saúde do serviço)
Filtre por unidades específicas do systemd para reduzir o ruído e focar nos serviços mais importantes

Em produção

Este guia usa um OpenTelemetry Collector separado para ler logs do systemd e enviá-los ao endpoint OTLP do ClickStack, que é o padrão recomendado para ambientes de produção.

Para ambientes de produção com vários hosts, considere:

Implantar o collector como um Conjunto de Daemon no Kubernetes
Executar o collector como um serviço systemd em cada host
Usar o OpenTelemetry Operator para automatizar a implantação

Consulte Ingestão com OpenTelemetry para ver padrões de implantação em produção.