Monitoramento dos logs de host do EC2 com ClickStack

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

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

# Verify instance metadata
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

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

# Ubuntu instances
ls -la /var/log/syslog

# Amazon Linux / RHEL instances
ls -la /var/log/messages

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages

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

# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version

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:

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

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

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

Inicie o OpenTelemetry Collector:

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

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

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

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:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  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

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

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

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

Baixar o arquivo de configuração do dashboard.

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

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