Monitorando logs do Systemd com o ClickStack

Em resumoColete e visualize logs do journal do systemd no ClickStack usando o journald receiver do OpenTelemetry Collector. Inclui um dataset de demonstração e um dashboard pré-configurado.

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

O receiver journald exige o binário journalctl para ler os arquivos do journal. A imagem oficial otel/opentelemetry-collector-contrib não inclui journalctl por padrão.Para implantações em contêineres, você pode instalar o collector diretamente no host ou criar uma imagem personalizada com utilitários do systemd. Consulte a seção de Solução de problemas para mais detalhes.

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 coletor 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

A demonstração usa o receiver filelog com logs em texto em vez de journald, para evitar a necessidade de journalctl no contêiner.

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 fonte como Logs
Defina o intervalo de tempo como 2025-11-14 00:00:00 - 2025-11-17 00:00:00

Exibição de fuso horárioO HyperDX exibe os timestamps no fuso horário local do navegador. Os dados de demonstração cobrem o período de 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC). O intervalo de tempo mais amplo garante que você verá os logs de demonstração independentemente da sua localização.

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.

a 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

Para o demo dataset, defina o intervalo de tempo como 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC) (ajuste com base no seu fuso horário local).

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

Colocando em produção

Este guia usa um OpenTelemetry Collector separado para ler logs do systemd e enviá-los ao endpoint OTLP do ClickStack, que é a abordagem recomendada para produção. Para ambientes de produção com vários hosts, considere:

Implantar o coletor como um Conjunto de Daemon no Kubernetes
Executar o coletor 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.

Features

Guides

Monitorando logs do Systemd com o ClickStack

Integração com sistemas existentes

Pré-requisitos

Obtenha a API key do ClickStack

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

Crie a configuração do OpenTelemetry Collector

Faça a implantação com Docker Compose

Verifique os logs no HyperDX

Dataset de demonstração

Baixar o conjunto de dados de exemplo

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

Executar o ClickStack com dados de demonstração

Verificar os logs no HyperDX

Dashboards e visualização

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

Nenhum log aparece no HyperDX

erro de `journalctl` não encontrado

Próximos passos

Colocando em produção

​Integração com sistemas existentes

Pré-requisitos

​Obtenha a API key do ClickStack

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

​Crie a configuração do OpenTelemetry Collector

​Faça a implantação com Docker Compose

​Verifique os logs no HyperDX

​Dataset de demonstração

​Baixar o conjunto de dados de exemplo

​Criar a configuração do coletor de demonstração

​Executar o ClickStack com dados de demonstração

​Verificar os logs no HyperDX

​Dashboards e visualização

​ a configuração do dashboard

​Importe o dashboard pré-configurado

​Visualize o dashboard

​Solução de problemas

​Nenhum log aparece no HyperDX

​erro de journalctl não encontrado

​Próximos passos

​Colocando em produção

Integração com sistemas existentes

Obtenha a API key do ClickStack

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

Crie a configuração do OpenTelemetry Collector

Faça a implantação com Docker Compose

Verifique os logs no HyperDX

Dataset de demonstração

Baixar o conjunto de dados de exemplo

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

Executar o ClickStack com dados de demonstração

Verificar os logs no HyperDX

Dashboards e visualização

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

Nenhum log aparece no HyperDX

erro de `journalctl` não encontrado

Próximos passos

Colocando em produção