Monitoramento dos logs de host do EC2 com ClickStack

Monitoramento dos logs de host do EC2 com ClickStack

Resumo

Colete e visualize logs do sistema de instâncias EC2 no ClickStack usando o OpenTelemetry Collector com enriquecimento automático de metadados da instância EC2 (ID da instância, região, AZ, tipo de instância). Inclui um dataset de demonstração e um dashboard pré-configurado.

​

Integração com uma instância EC2 existente

Esta seção aborda a instalação do OpenTelemetry Collector nas suas instâncias EC2 para coletar logs do sistema e enviá-los ao ClickStack com enriquecimento automático dos metadados da instância EC2. Essa arquitetura distribuída está pronta para produção e pode ser escalada para várias instâncias.

Executando o ClickStack na mesma instância EC2?

Se o ClickStack estiver em execução na mesma instância EC2 cujos logs você deseja monitorar, você pode usar a abordagem tudo-em-um, semelhante ao guia de logs de host genéricos. Monte /var/log no contêiner do ClickStack e adicione o processador resourcedetection à sua configuração personalizada para capturar automaticamente os metadados da EC2. Este guia se concentra na arquitetura distribuída, que é a mais comum em implantações de produção.

Se você quiser testar a integração de logs de host da EC2 antes de configurar sua instância de produção, pode usar nossa configuração pré-configurada e os dados de exemplo na seção “dataset de demonstração”.

Pré-requisitos

• Instância do ClickStack em execução (pode ser on-premises, na nuvem ou localmente)
• Instância EC2 em execução (Ubuntu, Amazon Linux ou outra distribuição Linux)
• Conectividade de rede entre a instância EC2 e o endpoint OTLP do ClickStack (porta 4318 para HTTP ou 4317 para gRPC)
• Serviço de metadados da instância EC2 acessível (habilitado por padrão)

1. ​

   Verifique se os metadados do EC2 estão acessíveis

   A partir da sua instância EC2, verifique se o serviço de metadados está acessível:

   # Obter token de metadados (IMDSv2)
   TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
   
   # Verificar metadados da instância
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type
   

   Você deverá ver o ID da instância, a região e o tipo de instância. Se esses comandos falharem, verifique:

   • Se o serviço de metadados da instância está habilitado
   • Se o IMDSv2 não está bloqueado por grupos de segurança ou ACLs de rede
   • Se você está executando esses comandos na própria instância EC2

   Os metadados da EC2 estão disponíveis em http://169.254.169.254 a partir da própria instância. O processador resourcedetection do OpenTelemetry usa esse endpoint para enriquecer automaticamente os logs com o contexto de nuvem.

2. ​

   Verifique se os arquivos de syslog existem

   Verifique se a sua instância EC2 está gravando os arquivos de syslog:

   # Instâncias Ubuntu
   ls -la /var/log/syslog
   
   # Instâncias Amazon Linux / RHEL
   ls -la /var/log/messages
   
   # Ver entradas recentes
   tail -20 /var/log/syslog
   # ou
   tail -20 /var/log/messages
   
3. ​

   Instale o OpenTelemetry Collector

   Instale a distribuição Contrib do OpenTelemetry Collector na instância EC2:

   # Baixe o lançamento mais recente
   wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz
   
   # Extraia e instale
   tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
   sudo mv otelcol-contrib /usr/local/bin/
   
   # Verifique a instalação
   otelcol-contrib --version
   
4. ​

   Criar configuração do collector

   Crie um arquivo de configuração para o OpenTelemetry Collector em /etc/otelcol-contrib/config.yaml:

   sudo mkdir -p /etc/otelcol-contrib
   

   Escolha a configuração com base na sua distribuição Linux:

   Linux moderno (Ubuntu 24.04+)

   sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
   receivers:
     filelog/syslog:
       include:
         - /var/log/syslog
         - /var/log/**/*.log
       start_at: end
       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_type: gotime
           layout: '2006-01-02T15:04:05.999999-07:00'
         
         - type: add
           field: attributes.source
           value: "ec2-host-logs"
   
   processors:
     resourcedetection:
       detectors: [ec2, system]
       timeout: 5s
       override: false
       ec2:
         tags:
           - ^Name
           - ^Environment
           - ^Team
     
     batch:
       timeout: 10s
       send_batch_size: 10000
   
   exporters:
     otlphttp:
       endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
       headers:
         authorization: "${env:CLICKSTACK_API_KEY}"
   
   service:
     pipelines:
       logs:
         receivers: [filelog/syslog]
         processors: [resourcedetection, batch]
         exporters: [otlphttp]
   EOF
   

   Linux legado (Amazon Linux 2, RHEL, versões mais antigas do Ubuntu)

   sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
   receivers:
     filelog/syslog:
       include:
         - /var/log/messages
         - /var/log/**/*.log
       start_at: end
       operators:
         - type: regex_parser
           regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?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: '%b %d %H:%M:%S'
         
         - type: add
           field: attributes.source
           value: "ec2-host-logs"
   
   processors:
     resourcedetection:
       detectors: [ec2, system]
       timeout: 5s
       override: false
       ec2:
         tags:
           - ^Name
           - ^Environment
           - ^Team
     
     batch:
       timeout: 10s
       send_batch_size: 10000
   
   exporters:
     otlphttp:
       endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
       headers:
         authorization: "${env:CLICKSTACK_API_KEY}"
   
   service:
     pipelines:
       logs:
         receivers: [filelog/syslog]
         processors: [resourcedetection, batch]
         exporters: [otlphttp]
   EOF
   

   
   

   Substitua o seguinte na configuração:

   • YOUR_CLICKSTACK_HOST: O hostname ou endereço IP em que o ClickStack está sendo executado
   • Para testes locais, você pode usar um túnel SSH (consulte a seção Solução de problemas)

   Esta configuração:

   • Lê arquivos de log do sistema nos locais padrão (/var/log/syslog para Ubuntu, /var/log/messages para Amazon Linux/RHEL)
   • Analisa o formato syslog para extrair campos estruturados (timestamp, hostname, unidade/serviço, PID, mensagem)
   • Detecta e adiciona automaticamente metadados da EC2 com o processador resourcedetection
   • Inclui, opcionalmente, tags do EC2 (Name, Environment, Team), se houver
   • Envia logs para o ClickStack via HTTP OTLP

   Enriquecimento de metadados do EC2

   O processador resourcedetection adiciona automaticamente estes atributos a cada log:

   • cloud.provider: “aws”
   • cloud.platform: “aws_ec2”
   • cloud.region: região da AWS (por exemplo, “us-east-1”)
   • cloud.availability_zone: zona de disponibilidade (por exemplo, “us-east-1a”)
   • cloud.account.id: ID da conta AWS
   • host.id: ID da instância do EC2 (por exemplo, “i-1234567890abcdef0”)
   • host.type: tipo de instância (por exemplo, “t3.medium”)
   • host.name: hostname da instância
5. ​

   Defina a chave de API do ClickStack

   Exporte sua chave de API do ClickStack como uma variável de ambiente:

   export CLICKSTACK_API_KEY="your-api-key-here"
   

   Para que isso persista após reinicializações, adicione ao perfil do seu shell:

   echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
   source ~/.bashrc
   
6. ​

   Inicie o collector

   Inicie o OpenTelemetry Collector:

   CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml
   

   Para uso em produção

   Configure o coletor para ser executado como um serviço do systemd, para que seja iniciado automaticamente na inicialização do sistema e reiniciado em caso de falha. Consulte a documentação do OpenTelemetry Collector para mais detalhes.

7. ​

   Verificando logs no HyperDX

   Quando o coletor estiver em execução, entre no HyperDX e verifique se os logs estão chegando com metadados do EC2:

   1. Acesse a tela de busca
   2. Defina a fonte como Logs
   3. Filtre por source:ec2-host-logs
   4. Clique em uma entrada de log para expandi-la
   5. Verifique se os atributos de recurso incluem metadados do EC2:
      • cloud.provider
      • cloud.region
      • host.id (ID da instância)
      • host.type (tipo de instância)
      • cloud.availability_zone

​

dataset de demonstração

Para quem quiser testar a integração de logs de host do EC2 antes de configurar as instâncias de produção, fornecemos um conjunto de dados de exemplo com metadados simulados da instância EC2.

1. ​

   Baixe 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/host-logs/journal.log
   

   O conjunto de dados inclui:

   • Sequência de inicialização do sistema
   • Atividade de login via SSH (tentativas bem-sucedidas e malsucedidas)
   • Incidente de segurança (ataque de força bruta com resposta do fail2ban)
   • Manutenção agendada (tarefas do cron, anacron)
   • Reinicializações de serviços (rsyslog)
   • Mensagens do kernel e atividade do firewall
   • Combinação de operações normais e eventos relevantes
2. ​

   Criar a configuração de teste do coletor

   Crie um arquivo chamado ec2-host-logs-demo.yaml com a seguinte configuração:

   cat > ec2-host-logs-demo.yaml << 'EOF'
   receivers:
     filelog/journal:
       include:
         - /tmp/host-demo/journal.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: "ec2-demo"
   
   processors:
     # Simula metadados do EC2 para demonstração (nenhuma instância EC2 real é necessária)
     resource:
       attributes:
         - key: service.name
           value: "ec2-demo"
           action: insert
         - key: cloud.provider
           value: "aws"
           action: insert
         - key: cloud.platform
           value: "aws_ec2"
           action: insert
         - key: cloud.region
           value: "us-east-1"
           action: insert
         - key: cloud.availability_zone
           value: "us-east-1a"
           action: insert
         - key: host.id
           value: "i-0abc123def456789"
           action: insert
         - key: host.type
           value: "t3.medium"
           action: insert
         - key: host.name
           value: "prod-web-01"
           action: insert
   
   service:
     pipelines:
       logs/ec2-demo:
         receivers: [filelog/journal]
         processors:
           - resource
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   EOF
   

   Para fins de demonstração, adicionamos manualmente os metadados da EC2 usando o processador resource. Em produção, com instâncias EC2 reais, use o processador resourcedetection, que consulta automaticamente a API de metadados da EC2.

3. ​

   Execute o ClickStack com a configuração de demonstração

   Execute o ClickStack com os logs e a configuração de demonstração:

   docker run --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)/ec2-host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
     docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest
   
4. ​

   Verifique os logs no HyperDX

   Quando o collector estiver em execução:

   1. Abra o HyperDX e entre na sua conta (talvez seja necessário criar uma conta primeiro)
   2. Acesse a Search view e defina a source como Logs
   3. Defina o intervalo de tempo como 2025-11-10 00:00:00 - 2025-11-13 00:00:00
   4. Filtre por source:ec2-demo
   5. Expanda uma entrada de log para ver os metadados da EC2 nos atributos de recurso

   Exibição do fuso horário

   O HyperDX exibe os timestamps no fuso horário local do seu navegador. Os dados de demonstração abrangem 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC). O intervalo de tempo mais amplo garante que você verá os logs de demonstração independentemente da sua localização. Depois que os logs aparecerem, você poderá reduzir o intervalo para um período de 24 horas para obter visualizações mais claras.

   Você deverá ver logs com contexto simulado da EC2, incluindo:

   • ID da instância: i-0abc123def456789
   • Região: us-east-1
   • Zona de disponibilidade: us-east-1a
   • Tipo de instância: t3.medium

​

Dashboards e visualizações

Para ajudar você a começar a monitorar logs de host do EC2 com o ClickStack, fornecemos visualizações essenciais com contexto de nuvem.

1. ​

   a configuração do dashboard

2. ​

   Importe o dashboard pré-configurado

   1. Abra o HyperDX e vá para a seção Dashboards
   2. Clique em Import Dashboard no canto superior direito, no menu de reticências

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

   Visualize o dashboard

   O dashboard será criado com todas as visualizações pré-configuradas:

   Você pode filtrar as visualizações do dashboard por contexto do EC2:

   • cloud.region:us-east-1 - Mostra logs de uma região específica
   • host.type:t3.medium - Filtra por tipo de instância
   • host.id:i-0abc123def456 - Logs de uma instância específica

   Para o dataset de demonstração, defina o intervalo de tempo como 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) (ajuste com base no seu fuso horário local). Por padrão, o dashboard importado não terá um intervalo de tempo especificado.

​

Solução de problemas

​

Os metadados da instância EC2 não aparecem nos logs

Verifique se o serviço de metadados da instância EC2 está acessível:

# Obter token de metadados
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Testar endpoint de metadados
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

Se isso falhar, verifique:

• Se o serviço de metadados da instância está habilitado
• Se o IMDSv2 não está bloqueado por grupos de segurança
• Se você está executando o collector na própria instância EC2

Verifique os logs do collector em busca de erros de metadados:

# Se estiver executando como serviço systemd
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# Se estiver executando em primeiro plano, verifique o stdout

​

Nenhum log aparece no HyperDX

Verifique se os arquivos de syslog existem e estão sendo gravados:

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

Verifique se o collector consegue ler os arquivos de log:

cat /var/log/syslog | head -20

Verifique a conexão de rede com o ClickStack:

# Testar o endpoint OTLP
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# Deve retornar uma resposta (mesmo que seja um erro, significa que o endpoint está acessível)

Verifique se há erros nos logs do collector:

# Se estiver executando em primeiro plano
# Procure mensagens de erro no stdout

# Se estiver executando como serviço systemd
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

​

Logs analisados incorretamente

Verifique o formato do seu syslog:

Para Ubuntu 24.04+:

# Deve exibir o formato ISO8601: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Para Amazon Linux 2 / Ubuntu 20.04:

# Deve exibir o formato tradicional: Nov 17 14:16:16
tail -5 /var/log/messages

Se o formato não corresponder ao seu caso, use a aba de configuração apropriada na seção Criar configuração do collector, com base na sua distribuição.

​

Collector não inicia como serviço systemd

Verifique o status do serviço:

sudo systemctl status otelcol-contrib

Veja logs detalhados:

sudo journalctl -u otelcol-contrib -n 50

Problemas comuns:

• API key não configurada corretamente no ambiente
• Erros de sintaxe no arquivo de configuração
• Problemas de permissão ao ler arquivos de log

​

Próximos passos

• Configure alertas para eventos críticos do sistema (falhas de serviço, falhas de autenticação, avisos de disco)
• Filtre por atributos de metadados da instância EC2 (região, tipo de instância, ID da instância) para monitorar recursos específicos
• Correlacione os logs de host do EC2 com os logs da aplicação para uma análise de problemas mais completa
• Crie dashboards personalizados para monitoramento de segurança (tentativas de SSH, uso de sudo, bloqueios de firewall)

​

Preparando para produção

Este guia instala o OpenTelemetry Collector diretamente em instâncias EC2, o que é a abordagem recomendada em produção para monitoramento em nível de host. Para gerenciar coletores em várias instâncias, considere usar ferramentas de gerenciamento de configuração (Ansible, Chef, Puppet) ou o OpenTelemetry Operator em ambientes Kubernetes. Consulte Enviando dados do OpenTelemetry para a configuração de produção.