Pular para o conteúdo principal
ResumoColete 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:
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

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 EC2O 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çãoConfigure 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árioO 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
  1. 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.
Última modificação em 10 de junho de 2026