Monitorización de logs de AWS CloudWatch con ClickStack

Monitorización de logs de AWS CloudWatch con ClickStack

En resumen

Reenvíe los logs de AWS CloudWatch a ClickStack mediante el CloudWatch receiver del OpenTelemetry Collector. Admite grupos de logs con nombre y autodescubrimiento. Incluye un dataset de demostración y un dashboard preconfigurado.

​

Descripción general

AWS CloudWatch es un servicio de monitorización para recursos y aplicaciones de AWS. Aunque CloudWatch ofrece agregación de logs, reenviar los logs a ClickStack le permite:

• Analizar logs junto con métricas y trazas en una plataforma unificada
• Consultar logs mediante la interfaz SQL de ClickHouse
• Reducir costos archivando los logs o reduciendo la retención en CloudWatch

Esta guía muestra cómo reenviar logs de CloudWatch a ClickStack mediante el OpenTelemetry Collector.

​

Integración con los grupos de logs existentes de CloudWatch

En esta sección se explica cómo configurar el OpenTelemetry Collector para extraer logs de sus grupos de logs existentes de CloudWatch y enviarlos a ClickStack.

Si desea probar la integración antes de configurar su entorno de producción, puede hacerlo con nuestro conjunto de datos de demostración en la sección del conjunto de datos de demostración.

​

Requisitos previos

• Instancia de ClickStack en ejecución
• Cuenta de AWS con grupos de logs de CloudWatch
• Credenciales de AWS con los permisos de IAM adecuados

A diferencia de las integraciones de logs basadas en archivos (nginx, Redis), CloudWatch requiere ejecutar un OpenTelemetry Collector independiente que consulta la API de CloudWatch. Este collector no puede ejecutarse dentro de la imagen todo en uno de ClickStack, ya que necesita credenciales de AWS y acceso a la API.

1. ​

   Obtener la API key de ClickStack

   El OpenTelemetry Collector envía datos al endpoint OTLP de ClickStack, que requiere autenticación.

   1. Abre HyperDX en la URL de tu instancia de ClickStack (p. ej., http://localhost:8080)
   2. Crea una cuenta o inicia sesión si es necesario
   3. Ve a Configuración del equipo → API keys
   4. Copia tu API key de ingesta

   Guarda esto en una variable de entorno:

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

   Configura las credenciales de AWS

   Exporta tus credenciales de AWS como variables de entorno. El método depende del tipo de autenticación:

   Para usuarios de AWS SSO (recomendado para la mayoría de las organizaciones):

   # Iniciar sesión en SSO
   aws sso login --profile YOUR_PROFILE_NAME
   
   # Exportar credenciales como variables de entorno
   eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)
   
   # Verificar que las credenciales funcionan
   aws sts get-caller-identity
   

   Sustituye YOUR_PROFILE_NAME por el nombre de tu perfil de AWS SSO (por ejemplo, AccountAdministrators-123456789).

   Para usuarios de IAM con credenciales permanentes:

   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 que las credenciales funcionan
   aws sts get-caller-identity
   

   Permisos de IAM necesarios:

   La cuenta de AWS asociada a estas credenciales necesita la siguiente política de IAM para leer los logs de CloudWatch:

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

   Sustituye YOUR_ACCOUNT_ID por el ID de tu cuenta de AWS.

3. ​

   Configura el receptor de CloudWatch

   Crea un archivo otel-collector-config.yaml con la configuración del receptor de CloudWatch.

   Descubre los grupos de logs disponibles en tu cuenta

   Antes de editar la configuración, enumera los grupos de logs que existen en tu región para poder elegir nombres reales (y confirmar que la región sea la correcta):

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

   Salida de ejemplo:

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

   Usa directamente los nombres de esta lista en el bloque groups.named del Ejemplo 1 a continuación. Para la cuenta anterior, la sección de grupos con nombre quedaría así:

   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, si los grupos que quieres usar comparten un prefijo común (aquí /aws-glue/), usa el Ejemplo 2 con prefix: /aws-glue/ en lugar de enumerarlos individualmente.

   Ejemplo 1: grupos de logs con nombre (recomendado)

   Esta configuración recopila logs de grupos de logs específicos con nombre:

   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]
   

   Ejemplo 2: Detectar automáticamente grupos de logs por prefijo

   Esta configuración detecta automáticamente y recopila logs de hasta 100 grupos de logs que empiezan por el prefijo /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 configuración:

   • region: Región de AWS donde se encuentran tus grupos de logs
   • poll_interval: Frecuencia con la que se comprueba si hay logs nuevos (p. ej., 1m, 5m)
   • max_events_per_request: Número máximo de eventos de log que se obtienen en cada solicitud
   • groups.autodiscover.limit: Número máximo de grupos de logs que se pueden detectar automáticamente
   • groups.autodiscover.prefix: Filtra los grupos de logs por prefijo
   • groups.named: Lista explícitamente los nombres de los grupos de logs que se recopilarán

   Para ver más opciones de configuración, consulta la documentación del CloudWatch receiver.

   Reemplaza lo siguiente:

   • ${CLICKSTACK_API_KEY} → Usa la variable de entorno que configuraste antes
   • http://localhost:4318 → Tu endpoint de ClickStack (usa tu host de ClickStack si se ejecuta de forma remota)
   • us-east-1 → Tu región de AWS
   • Log group names/prefixes → Tus nombres o prefijos reales de grupos de logs de CloudWatch

   El CloudWatch receiver solo obtiene logs de ventanas de tiempo recientes (según poll_interval). Cuando se inicia por primera vez, comienza desde la hora actual. Los logs históricos no se recuperan de forma predeterminada.

4. ​

   Inicie el collector

   Cree un archivo 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"
   

   A continuación, inicie el collector:

   docker compose up -d
   

   Ver los logs del collector:

   docker compose logs -f otel-collector
   
5. ​

   Verificar los logs en HyperDX

   Una vez que el collector esté en funcionamiento:

   1. Abra HyperDX en http://localhost:8080 (o en la URL de ClickStack)
   2. Vaya a la vista de Logs
   3. Espere 1-2 minutos a que aparezcan los logs (según el intervalo de sondeo configurado)
   4. Busque logs de sus grupos de logs de CloudWatch

   Busque estos atributos clave en los logs:

   • ResourceAttributes['aws.region']: Su región de AWS (p. ej., “us-east-1”)
   • ResourceAttributes['cloudwatch.log.group.name']: El nombre del grupo de logs de CloudWatch
   • ResourceAttributes['cloudwatch.log.stream']: El nombre del stream de logs
   • Body: El contenido real del mensaje de log

​

Conjunto de datos de demostración

Para quienes quieran probar la integración de CloudWatch Logs antes de configurar su entorno de producción en AWS, proporcionamos un conjunto de datos de ejemplo con logs pregenerados que muestran patrones realistas de varios servicios de AWS.

1. ​

   Descargar el conjunto de datos de ejemplo

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

   El conjunto de datos incluye 24 horas de logs de CloudWatch Logs de varios servicios:

   • Funciones Lambda: procesamiento de pagos, gestión de pedidos, autenticación
   • Servicios de ECS: API gateway con limitación de tasa y timeouts
   • Trabajos en segundo plano: procesamiento por lotes con patrones de reintento
2. ​

   Iniciar ClickStack

   Si todavía no tienes ClickStack en ejecución:

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

   Espera unos momentos a que ClickStack termine de iniciarse por completo.

3. ​

   Importar el conjunto de datos de demostración

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

   Esto importa los logs directamente en la tabla de logs de ClickStack.

4. ​

   Verificar los datos de demostración

   Una vez importados:

   1. Abre HyperDX en http://localhost:8080 e inicia sesión (crea una cuenta si es necesario)
   2. Ve a la vista de Logs
   3. Establece el intervalo de tiempo en 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)
   4. Busca cloudwatch-demo o filtra por LogAttributes['source'] = 'cloudwatch-demo'

   Deberías ver logs de varios grupos de logs de CloudWatch.

   Visualización de la zona horaria

   HyperDX muestra las marcas de tiempo en la zona horaria local de tu navegador. Los datos de demostración abarcan 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC). Establece el intervalo de tiempo en 2025-12-06 00:00:00 - 2025-12-09 00:00:00 para asegurarte de ver los logs de demostración independientemente de tu ubicación. Una vez que veas los logs, puedes reducir el intervalo a un período de 24 horas para obtener visualizaciones más claras.

​

Paneles y visualización

Para ayudarte a supervisar los logs de CloudWatch con ClickStack, proporcionamos un dashboard preconfigurado con las visualizaciones esenciales.

1. ​

   la configuración del dashboard

2. ​

   Importar el dashboard

   1. Abre HyperDX y ve a la sección Dashboards
   2. Haz clic en Import Dashboard en la esquina superior derecha, dentro del menú de puntos suspensivos

   3. Sube el archivo cloudwatch-logs-dashboard.json y haz clic en Finish Import
3. ​

   Ver el dashboard

   El dashboard se creará con todas las visualizaciones ya configuradas:

   Para el conjunto de datos de demostración, establece el intervalo de tiempo en 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC) (ajústalo según tu zona horaria local). El dashboard importado no tendrá un intervalo de tiempo especificado de forma predeterminada.

​

Solución de problemas

​

No aparecen logs en HyperDX

Verifique que las credenciales de AWS estén configuradas:

aws sts get-caller-identity

Si esto falla, sus credenciales no son válidas o han caducado.

Compruebe los permisos de IAM: Asegúrese de que sus credenciales de AWS tengan los permisos necesarios logs:DescribeLogGroups y logs:FilterLogEvents.

Compruebe los logs del collector para ver si hay errores:

# Si se usa Docker directamente, los logs aparecen en stdout
# Si se usa Docker Compose:
docker compose logs otel-collector

Errores comunes:

• The security token included in the request is invalid: las credenciales no son válidas o han expirado. Si usas credenciales temporales (SSO), asegúrate de que AWS_SESSION_TOKEN esté configurado.
• operation error CloudWatch Logs: FilterLogEvents, AccessDeniedException: los permisos de IAM son insuficientes
• failed to refresh cached credentials, no EC2 IMDS role found: las variables de entorno de las credenciales de AWS no están configuradas
• connection refused: no se puede acceder al endpoint de ClickStack

Verifica que existan los CloudWatch log groups y que tengan logs recientes:

# Lista tus grupos de logs
aws logs describe-log-groups --region us-east-1

# Comprueba si un grupo de logs específico tiene logs recientes (ú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

​

Solo ves logs antiguos o faltan logs recientes

El receiver de CloudWatch empieza en “ahora” de forma predeterminada:

Cuando el collector se inicia por primera vez, crea un punto de control en el momento actual y solo obtiene logs posteriores a ese momento. No se recuperan logs históricos.

Para recopilar logs históricos recientes:

Detén y elimina el punto de control del collector y, a continuación, reinícialo:

# Detener el collector
docker stop <container-id>

# Reiniciar desde cero (los checkpoints se almacenan en el contenedor, por lo que eliminarlo los restablece)
docker run --rm ...

El receiver creará un nuevo checkpoint y recuperará logs a partir de ese momento.

​

Token de seguridad no válido / credenciales caducadas

Si usas credenciales temporales (AWS SSO, rol asumido), caducan al cabo de un tiempo.

Vuelve a exportar credenciales vigentes:

# Para usuarios de SSO:
aws sso login --profile YOUR_PROFILE_NAME
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Para usuarios de IAM:
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# Reiniciar el collector
docker restart <container-id>

​

Latencia alta o falta de logs recientes

Reduce el intervalo de sondeo: El poll_interval predeterminado es de 1 minuto. Para obtener logs casi en tiempo real, redúzcalo:

logs:
  poll_interval: 30s  # Consultar cada 30 segundos

Nota: Los intervalos de sondeo más cortos aumentan las llamadas a la API de AWS y pueden generar costos más altos en la API de CloudWatch.

​

El collector consume demasiada memoria

Reduzca el tamaño del batch o aumente el tiempo de espera:

processors:
  batch:
    timeout: 5s
    send_batch_size: 100

Limita el autodescubrimiento:

groups:
  autodiscover:
    limit: 50  # Reducir de 100 a 50

​

Próximos pasos

• Configura alertas para eventos críticos (fallos de conexión, picos de errores)
• Reduce los costos de CloudWatch ajustando los períodos de retención o archivando los logs en S3, ahora que ya están en ClickStack
• Filtra los grupos de logs más ruidosos eliminándolos de la configuración del collector para reducir el volumen de ingestión

​

Paso a producción

Esta guía muestra cómo ejecutar OpenTelemetry Collector localmente con Docker Compose para hacer pruebas. Para implementaciones de producción, ejecute el collector en infraestructura con acceso a AWS (EC2 con roles de IAM, EKS con IRSA o ECS con roles de tarea) para evitar tener que administrar claves de acceso. Implemente los collectors en la misma región de AWS que sus grupos de logs de CloudWatch para reducir la latencia y los costos.

Consulte Ingestar con OpenTelemetry para ver patrones de implementación en producción y ejemplos de configuración del collector.