Monitoramento de logs do CloudWatch da AWS com ClickStack

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.

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.

• 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

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"

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):

# Login to SSO
aws sso login --profile YOUR_PROFILE_NAME

# Export credentials to environment variables
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Verify credentials work
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"

# Verify credentials work
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.

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

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

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

Para usuários que desejam testar a integração com os logs do CloudWatch 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.

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

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.

Importe o conjunto de dados 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.

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.

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

Baixe a configuração do dashboard

Baixe o arquivo de configuração do dashboard.

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

Visualize o dashboard

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

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

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.

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>

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.

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

• 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

Este guia mostra 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 IAM roles, EKS com IRSA ou ECS com task roles) 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.