Monitoramento de logs do CloudWatch da AWS com ClickStack

Monitoramento de logs do CloudWatch da AWS com ClickStack

Resumo

Encaminhe logs do AWS CloudWatch para o ClickStack usando o CloudWatch receiver do OpenTelemetry Collector. Compatível com grupos de logs nomeados e descoberta automática. Inclui um conjunto de dados de demonstração e um dashboard pré-configurado.

​

Visão geral

O AWS CloudWatch é um serviço de monitoramento para recursos e aplicações da AWS. Embora o CloudWatch ofereça agregação de logs, encaminhar logs para o ClickStack permite:

• Analisar logs junto com métricas e traces em uma plataforma unificada
• Consultar logs usando a interface SQL do ClickHouse
• Reduzir custos arquivando logs ou diminuindo a retenção no CloudWatch

Este guia mostra como encaminhar logs do CloudWatch para o ClickStack usando o OpenTelemetry Collector.

​

Integração com grupos de logs existentes do CloudWatch

Esta seção aborda a configuração do OpenTelemetry Collector para extrair logs dos seus grupos de logs existentes do CloudWatch e encaminhá-los ao ClickStack.

Se quiser testar a integração antes de configurar seu ambiente de produção, você pode fazer isso com nosso conjunto de dados de demonstração na seção do conjunto de dados de demonstração.

​

Pré-requisitos

• Instância do ClickStack em execução
• Conta da AWS com grupos de logs do CloudWatch
• Credenciais da AWS com as permissões de IAM adequadas

Ao contrário das integrações de logs baseadas em arquivos (nginx, Redis), o CloudWatch exige a execução de um OpenTelemetry Collector separado, que consulta periodicamente a API do CloudWatch. Esse collector não pode ser executado dentro da imagem tudo-em-um do ClickStack, pois precisa de credenciais da AWS e acesso à API.

1. ​

   Obter a API key do ClickStack

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

   1. Abra o HyperDX na URL do seu ClickStack (por exemplo, http://localhost:8080)
   2. Crie uma conta ou faça login, se necessário
   3. Acesse Configurações da equipe → API Keys
   4. Copie sua API key de ingestão

   Salve isso em uma variável de ambiente:

   export CLICKSTACK_API_KEY="your-api-key-here"
   
2. ​

   Configurar as credenciais da AWS

   Exporte suas credenciais da AWS como variáveis de ambiente. O método depende do tipo de autenticação usado:

   Para usuários do AWS SSO (recomendado para a maioria das organizações):

   # Fazer login no SSO
   aws sso login --profile YOUR_PROFILE_NAME
   
   # Exportar credenciais para variáveis de ambiente
   eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)
   
   # Verificar se as credenciais funcionam
   aws sts get-caller-identity
   

   Substitua YOUR_PROFILE_NAME pelo nome do seu perfil do AWS SSO (por exemplo, AccountAdministrators-123456789).

   Para usuários do IAM com credenciais de longo prazo:

   export AWS_ACCESS_KEY_ID="your-access-key-id"
   export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
   export AWS_REGION="us-east-1"
   
   # Verificar se as credenciais funcionam
   aws sts get-caller-identity
   

   Permissões necessárias do IAM:

   A conta da AWS associada a essas credenciais precisa da seguinte política do IAM para ler logs do CloudWatch:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "CloudWatchLogsRead",
         "Effect": "Allow",
         "Action": [
           "logs:DescribeLogGroups",
           "logs:FilterLogEvents"
         ],
         "Resource": "arn:aws:logs:*:YOUR_ACCOUNT_ID:log-group:*"
       }
     ]
   }
   

   Substitua YOUR_ACCOUNT_ID pelo ID da sua conta na AWS.

3. ​

   Configure o receiver do CloudWatch

   Crie um arquivo otel-collector-config.yaml com a configuração do receiver do CloudWatch.

   Descubra os grupos de logs disponíveis na sua conta

   Antes de editar a configuração, liste os grupos de logs existentes na sua região para escolher nomes reais (e confirmar que a região está correta):

   aws logs describe-log-groups --region us-east-1 \
     --query 'logGroups[].logGroupName' --output table
   

   Saída de exemplo:

   -------------------------------
   |      DescribeLogGroups      |
   +-----------------------------+
   |  /aws-glue/jobs/error       |
   |  /aws-glue/jobs/logs-v2     |
   |  /aws-glue/jobs/output      |
   |  /aws-glue/sessions/error   |
   |  /aws-glue/sessions/output  |
   +-----------------------------+
   

   Use os nomes desta lista diretamente no bloco groups.named do Exemplo 1 abaixo. Para a conta acima, a seção named-groups ficaria assim:

   groups:
     named:
       /aws-glue/jobs/error:
       /aws-glue/jobs/logs-v2:
       /aws-glue/jobs/output:
       /aws-glue/sessions/error:
       /aws-glue/sessions/output:
   

   Como alternativa, se os grupos desejados tiverem um prefixo em comum (neste caso, /aws-glue/), use o Exemplo 2 com prefix: /aws-glue/ em vez de listá-los individualmente.

   Exemplo 1: Grupos de logs nomeados (recomendado)

   Esta configuração coleta logs de grupos de logs nomeados específicos:

   receivers:
     awscloudwatch:
       region: us-east-1
       logs:
         poll_interval: 1m
         max_events_per_request: 100
         groups:
           named:
             /aws/lambda/my-function:
             /aws/ecs/my-service:
             /aws/eks/my-cluster/cluster:
   
   processors:
     batch:
       timeout: 10s
   
   exporters:
     otlphttp:
       endpoint: http://localhost:4318
       headers:
         authorization: ${CLICKSTACK_API_KEY}
   
   service:
     pipelines:
       logs:
         receivers: [awscloudwatch]
         processors: [batch]
         exporters: [otlphttp]
   

   Exemplo 2: Descoberta automática de grupos de logs com prefixo

   Esta configuração detecta e coleta automaticamente logs de até 100 grupos de logs cujo nome começa com o prefixo /aws/lambda:

   receivers:
     awscloudwatch:
       region: us-east-1
       logs:
         poll_interval: 1m
         max_events_per_request: 100
         groups:
           autodiscover:
             limit: 100
             prefix: /aws/lambda
   
   processors:
     batch:
       timeout: 10s
   
   exporters:
     otlphttp:
       endpoint: http://localhost:4318
       headers:
         authorization: ${CLICKSTACK_API_KEY}
   
   service:
     pipelines:
       logs:
         receivers: [awscloudwatch]
         processors: [batch]
         exporters: [otlphttp]
   

   Parâmetros de configuração:

   • region: Região da AWS onde seus grupos de logs estão localizados
   • poll_interval: Frequência de verificação de novos logs (por exemplo, 1m, 5m)
   • max_events_per_request: Número máximo de eventos de log buscados por solicitação
   • groups.autodiscover.limit: Número máximo de grupos de logs a descobrir
   • groups.autodiscover.prefix: Filtra grupos de logs por prefixo
   • groups.named: Lista explicitamente os nomes dos grupos de logs a serem coletados

   Para mais opções de configuração, consulte a documentação do CloudWatch receiver.

   Substitua o seguinte:

   • ${CLICKSTACK_API_KEY} → Usa a variável de ambiente definida anteriormente
   • http://localhost:4318 → Seu endpoint do ClickStack (use o host do seu ClickStack se estiver em execução remota)
   • us-east-1 → Sua região da AWS
   • Nomes/prefixos de grupos de logs → Seus grupos de logs do CloudWatch reais

   O CloudWatch receiver busca logs apenas em janelas de tempo recentes (com base em poll_interval). Quando é iniciado pela primeira vez, começa a partir do horário atual. Logs históricos n’o são recuperados por padrão.

4. ​

   Inicie o coletor

   Crie um arquivo docker-compose.yaml:

   services:
     otel-collector:
       image: otel/opentelemetry-collector-contrib:latest
       command: ["--config=/etc/otel-config.yaml"]
       volumes:
         - ./otel-collector-config.yaml:/etc/otel-config.yaml
       environment:
         - AWS_ACCESS_KEY_ID
         - AWS_SECRET_ACCESS_KEY
         - AWS_SESSION_TOKEN
         - AWS_REGION
         - CLICKSTACK_API_KEY
       restart: unless-stopped
       extra_hosts:
         - "host.docker.internal:host-gateway"
   

   Em seguida, inicie o coletor:

   docker compose up -d
   

   Veja os logs do collector:

   docker compose logs -f otel-collector
   
5. ​

   Verifique os logs no HyperDX

   Quando o coletor estiver em execução:

   1. Abra o HyperDX em http://localhost:8080 (ou na URL do seu ClickStack)
   2. Acesse a visualização Logs
   3. Aguarde 1 a 2 minutos para que os logs apareçam (dependendo do seu intervalo de polling)
   4. Pesquise logs dos seus grupos de logs do CloudWatch

   Procure estes atributos principais nos logs:

   • ResourceAttributes['aws.region']: Sua região da AWS (por exemplo, “us-east-1”)
   • ResourceAttributes['cloudwatch.log.group.name']: O nome do grupo de logs do CloudWatch
   • ResourceAttributes['cloudwatch.log.stream']: O nome do fluxo de logs
   • Body: O conteúdo da mensagem de log

​

Dataset de demonstração

Para usuários que desejam testar a integração com o CloudWatch Logs antes de configurar o ambiente de produção na AWS, fornecemos um dataset de exemplo com logs pré-gerados que mostram padrões realistas de vários serviços da AWS.

1. ​

   Baixe o dataset de exemplo

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/aws/cloudwatch/cloudwatch-logs.jsonl
   

   O dataset inclui 24 horas de logs do CloudWatch de vários serviços:

   • Funções Lambda: processamento de pagamentos, gerenciamento de pedidos, autenticação
   • Serviços ECS: gateway de API com limitação de taxa e timeouts
   • Jobs em segundo plano: processamento em lote com padrões de retry
2. ​

   Inicie o ClickStack

   Se o ClickStack ainda não estiver em execução:

   docker run -d --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

   Aguarde alguns instantes até o ClickStack iniciar completamente.

3. ​

   Importe o dataset de demonstração

   docker exec -i clickstack clickhouse-client --query="
     INSERT INTO default.otel_logs FORMAT JSONEachRow
   " < cloudwatch-logs.jsonl
   

   Isso importa os logs diretamente para a tabela de logs do ClickStack.

4. ​

   Verifique os dados de demonstração

   Depois da importação:

   1. Abra o HyperDX em http://localhost:8080 e faça login (crie uma conta, se necessário)
   2. Acesse a visualização Logs
   3. Defina o intervalo de tempo como 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)
   4. Pesquise por cloudwatch-demo ou filtre por LogAttributes['source'] = 'cloudwatch-demo'

   Você deverá ver logs de vários grupos de logs do CloudWatch.

   Exibição de fuso horário

   O HyperDX exibe os timestamps no fuso horário local do seu navegador. Os dados de demonstração abrangem 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC). Defina o intervalo de tempo como 2025-12-06 00:00:00 - 2025-12-09 00:00:00 para garantir que você veja os logs de demonstração independentemente da sua localização. Depois de ver os logs, você pode restringir o intervalo para um período de 24 horas para visualizações mais claras.

​

Dashboards e visualização

Para ajudar você a monitorar os logs do CloudWatch com o ClickStack, fornecemos um dashboard pré-configurado com visualizações essenciais.

1. ​

   a configuração do dashboard

2. ​

   Importe o dashboard

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

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

   Visualize o dashboard

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

   Para o dataset de demonstração, defina o intervalo de tempo como 2025-12-07 00:00:00 - 2025-12-08 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

​

Nenhum log aparece no HyperDX

Verifique se as credenciais da AWS estão configuradas:

aws sts get-caller-identity

Se isso falhar, suas credenciais são inválidas ou estão expiradas.

Verifique as permissões do IAM: Certifique-se de que suas credenciais da AWS tenham as permissões logs:DescribeLogGroups e logs:FilterLogEvents necessárias.

Verifique os logs do collector em busca de erros:

# Se estiver usando o Docker diretamente, os logs aparecem no stdout
# Se estiver usando o Docker Compose:
docker compose logs otel-collector

Erros comuns:

• The security token included in the request is invalid: As credenciais são inválidas ou expiraram. Para credenciais temporárias (SSO), verifique se AWS_SESSION_TOKEN está definido.
• operation error CloudWatch Logs: FilterLogEvents, AccessDeniedException: As permissões do IAM são insuficientes
• failed to refresh cached credentials, no EC2 IMDS role found: As variáveis de ambiente das credenciais da AWS não estão definidas
• connection refused: Não é possível acessar o endpoint do ClickStack

Verifique se os grupos de logs do CloudWatch existem e contêm logs recentes:

# Liste seus grupos de logs
aws logs describe-log-groups --region us-east-1

# Verifique se um grupo de logs específico tem logs recentes (última hora)
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --region us-east-1 \
  --start-time $(date -u -v-1H +%s)000 \
  --max-items 5

​

Apenas logs antigos aparecem ou logs recentes estão faltando

O CloudWatch receiver começa em “agora” por padrão:

Quando o collector é iniciado pela primeira vez, ele cria um checkpoint no momento atual e só busca logs após esse ponto. Logs históricos não são recuperados.

Para coletar logs históricos recentes:

Pare e remova o checkpoint do collector e, em seguida, reinicie:

# Pare o collector
docker stop <container-id>

# Reinicie do zero (os checkpoints são armazenados no container, então removê-lo os redefine)
docker run --rm ...

O receiver criará um novo checkpoint e buscará logs a partir de agora.

​

Token de segurança inválido / credenciais expiradas

Se você estiver usando credenciais temporárias (AWS SSO, função assumida), elas expiram após algum tempo.

Exporte novamente credenciais atualizadas:

# Para usuários SSO:
aws sso login --profile YOUR_PROFILE_NAME
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Para usuários IAM:
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# Reinicie o collector
docker restart <container-id>

​

Alta latência ou falta de logs recentes

Reduza o intervalo de polling: O poll_interval padrão é de 1 minuto. Para logs quase em tempo real, reduza-o:

logs:
  poll_interval: 30s  # Consulta a cada 30 segundos

Observação: Intervalos de polling menores aumentam as chamadas à API da AWS e podem gerar custos mais altos com a API do CloudWatch.

​

Collector consumindo memória demais

Reduza o tamanho do batch ou aumente o timeout:

processors:
  batch:
    timeout: 5s
    send_batch_size: 100

Restrinja a descoberta automática:

groups:
  autodiscover:
    limit: 50  # Reduzir de 100 para 50

​

Próximos passos

• Configure alertas para eventos críticos (falhas de conexão, picos de erros)
• Reduza os custos do CloudWatch ajustando os períodos de retenção ou arquivando no S3, agora que você já tem logs no ClickStack
• Filtre grupos de logs com muito ruído removendo-os da configuração do collector para reduzir o volume de ingestão

​

Colocando em produção

Este guia demonstra como executar o OpenTelemetry Collector localmente com Docker Compose para testes. Para implantações em produção, execute o collector em uma infraestrutura com acesso à AWS (EC2 com funções do IAM, EKS com IRSA ou ECS com funções de tarefa) para eliminar a necessidade de gerenciar chaves de acesso. Implante os collectors na mesma região da AWS que seus grupos de logs do CloudWatch para reduzir a latência e os custos.

Consulte Ingestão com OpenTelemetry para ver padrões de implantação em produção e exemplos de configuração do collector.