Monitorización de logs de host de EC2 con ClickStack

TL;DRRecopila y visualiza logs del sistema de EC2 en ClickStack con OpenTelemetry Collector y enriquecimiento automático de metadatos de EC2 (ID de instancia, región, AZ, tipo de instancia). Incluye un dataset de demostración y un dashboard preconfigurado.

Integración con una instancia de EC2 existente

Esta sección explica cómo instalar OpenTelemetry Collector en sus instancias de EC2 para recopilar logs del sistema y enviarlos a ClickStack con enriquecimiento automático de metadatos de EC2. Esta arquitectura distribuida está lista para producción y escala a varias instancias.

¿Ejecuta ClickStack en la misma instancia de EC2?Si ClickStack se ejecuta en la misma instancia de EC2 cuyos logs quiere supervisar, puede usar un enfoque todo en uno, similar al de la guía de logs de host genéricos. Monte /var/log en el contenedor de ClickStack y agregue el procesador resourcedetection a su configuración personalizada para capturar automáticamente los metadatos de EC2. Esta guía se centra en la arquitectura distribuida, que es la más habitual para implementaciones en producción.

Si desea probar la integración de logs de host de EC2 antes de configurar su instancia de producción, puede hacerlo con nuestra configuración preconfigurada y datos de muestra en la sección “Conjunto de datos de demostración”.

Requisitos previos

Instancia de ClickStack en ejecución (puede ser on-premise, en la nube o local)
Instancia de EC2 en ejecución (Ubuntu, Amazon Linux u otra distribución de Linux)
Conectividad de red desde la instancia de EC2 hasta el endpoint OTLP de ClickStack (puerto 4318 para HTTP o 4317 para gRPC)
Servicio de metadatos de la instancia de EC2 accesible (habilitado de forma predeterminada)

Verifique que se pueda acceder a los metadatos de EC2

Desde su instancia de EC2, verifique que se pueda acceder al servicio de metadatos:

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

# Verificar metadatos de la instancia
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

Deberías ver el ID de la instancia, la región y el tipo de instancia. Si estos comandos fallan, verifica lo siguiente:

Que el servicio de metadatos de la instancia esté habilitado
Que IMDSv2 no esté bloqueado por grupos de seguridad ni por ACL de red
Que estés ejecutando estos comandos desde la propia instancia de EC2

Los metadatos de EC2 están disponibles en http://169.254.169.254 desde dentro de la instancia. El procesador resourcedetection de OpenTelemetry usa este endpoint para enriquecer automáticamente los logs con contexto de nube.

Verifique que existan archivos de syslog

Verifique que su instancia de EC2 esté escribiendo archivos de syslog:

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

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

# Ver entradas recientes
tail -20 /var/log/syslog
# o
tail -20 /var/log/messages

Instalar OpenTelemetry Collector

Instale la distribución Contrib del OpenTelemetry Collector en su instancia de EC2:

# Descargar la última versión
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extraer e instalar
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verificar la instalación
otelcol-contrib --version

Crear la configuración del collector

Cree un archivo de configuración para el OpenTelemetry Collector en /etc/otelcol-contrib/config.yaml:

sudo mkdir -p /etc/otelcol-contrib

Elija la configuración según su distribución de Linux:

Linux moderno (Ubuntu 24.04+)
Linux heredado (Amazon Linux 2, RHEL y versiones anteriores de Ubuntu)

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

Reemplace lo siguiente en la configuración:

YOUR_CLICKSTACK_HOST: El nombre de host o la dirección IP en la que se ejecuta ClickStack
Para pruebas locales, puedes usar un túnel SSH (consulta la sección de solución de problemas)

Esta configuración:

Lee los archivos de registro del sistema desde ubicaciones estándar (/var/log/syslog para Ubuntu, /var/log/messages para Amazon Linux/RHEL)
Analiza el formato syslog para extraer campos estructurados (marca temporal, hostname, unidad/servicio, PID, mensaje)
Detecta y añade automáticamente los metadatos de EC2 usando el procesador resourcedetection
Opcionalmente, incluye las etiquetas de EC2 (Name, Environment, Team) si están presentes
Envía logs a ClickStack mediante OTLP HTTP

Enriquecimiento de metadatos de EC2El procesador resourcedetection añade automáticamente estos atributos a cada registro:

cloud.provider: “aws”
cloud.platform: “aws_ec2”
cloud.region: región de AWS (p. ej., “us-east-1”)
cloud.availability_zone: zona de disponibilidad (p. ej., “us-east-1a”)
cloud.account.id: ID de la cuenta de AWS
host.id: ID de la instancia de EC2 (p. ej., “i-1234567890abcdef0”)
host.type: tipo de instancia (p. ej., “t3.medium”)
host.name: nombre de host de la instancia

Configura la API key de ClickStack

Exporta tu API key de ClickStack como variable de entorno:

export CLICKSTACK_API_KEY="your-api-key-here"

Para que esto se mantenga tras reiniciar, agrégalo al perfil de tu shell:

echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Ejecuta el collector

Inicia el OpenTelemetry Collector:

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

Para uso en producciónConfigure el collector para que se ejecute como un servicio de systemd, de modo que se inicie automáticamente al arrancar y se reinicie en caso de fallo. Consulte la documentación de OpenTelemetry Collector para obtener más información.

Verificación de logs en HyperDX

Una vez que el collector esté en ejecución, inicia sesión en HyperDX y verifica que los logs estén llegando con metadatos de EC2:

Ve a la vista de búsqueda
Establece source en Logs
Filtra por source:ec2-host-logs
Haz clic en una entrada de log para expandirla
Verifica que aparezcan metadatos de EC2 en los atributos del recurso:
- cloud.provider
- cloud.region
- host.id (ID de instancia)
- host.type (tipo de instancia)
- cloud.availability_zone

Conjunto de datos de demostración

Para quienes quieran probar la integración de log de host de EC2 antes de configurar sus instancias de producción, proporcionamos un conjunto de datos de ejemplo con metadatos simulados de EC2.

Descarga el conjunto de datos de ejemplo

Descarga el archivo de logs de ejemplo:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

El conjunto de datos incluye:

Secuencia de arranque del sistema
Actividad de inicio de sesión por SSH (intentos exitosos y fallidos)
Incidente de seguridad (ataque de fuerza bruta con respuesta de fail2ban)
Mantenimiento programado (tareas de cron, anacron)
Reinicios de servicios (rsyslog)
Mensajes del kernel y actividad del firewall
Combinación de operaciones normales y eventos destacados

Crear una configuración de prueba para el collector

Cree un archivo llamado ec2-host-logs-demo.yaml con la siguiente configuración:

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:
  # Simular metadatos de EC2 para la demo (no se necesita una instancia EC2 real)
  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 fines de demostración, añadimos manualmente metadatos de EC2 mediante el procesador resource. En producción, con instancias reales de EC2, use el procesador resourcedetection, que consulta automáticamente la API de metadatos de EC2.

Ejecutar ClickStack con la configuración de demostración

Ejecute ClickStack con los logs y la configuración de demostración:

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

Verifica los logs en HyperDX

Una vez que el collector esté en ejecución:

Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una cuenta)
Ve a la vista de búsqueda y establece el source en Logs
Establece el intervalo de tiempo en 2025-11-10 00:00:00 - 2025-11-13 00:00:00
Filtra por source:ec2-demo
Expande una entrada de log para ver los metadatos de EC2 en los atributos del recurso

Visualización de la zona horariaHyperDX muestra los timestamps en la zona horaria local de tu navegador. Los datos de demostración abarcan 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC). El intervalo de tiempo amplio garantiza que veas 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.

Deberías ver logs con un contexto simulado de EC2 que incluye:

ID de instancia: i-0abc123def456789
Región: us-east-1
Zona de disponibilidad: us-east-1a
Tipo de instancia: t3.medium

Paneles y visualización

Para ayudarte a empezar a monitorizar el log de host de EC2 con ClickStack, proporcionamos visualizaciones esenciales con contexto de la nube.

la configuración del dashboard

Importa el dashboard preconfigurado

Abre HyperDX y ve a la sección Dashboards
Haz clic en Import Dashboard en la esquina superior derecha, en el menú de los tres puntos

Sube el archivo host-logs-dashboard.json y haz clic en Finish Import

Ver el dashboard

El dashboard se creará con todas las visualizaciones ya configuradas:Puedes filtrar las visualizaciones del dashboard por contexto de EC2:

cloud.region:us-east-1 - Muestra logs de una región específica
host.type:t3.medium - Filtra por tipo de instancia
host.id:i-0abc123def456 - Logs de una instancia específica

Para el conjunto de datos de demostración, establece el intervalo de tiempo en 2025-11-11 00:00:00 - 2025-11-12 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

Los metadatos de EC2 no aparecen en los logs

Verifica que el servicio de metadatos de EC2 sea accesible:

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

# Probar el endpoint de metadatos
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

Si esto falla, compruebe lo siguiente:

El servicio de metadatos de la instancia está habilitado
IMDSv2 no está bloqueado por los grupos de seguridad
Está ejecutando el collector en la propia instancia EC2

Revise los logs del collector para detectar errores de metadatos:

# Si se ejecuta como servicio de systemd
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# Si se ejecuta en primer plano, revisar stdout

No se muestran logs en HyperDX

Verifica que los archivos de syslog existan y que se estén escribiendo:

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

Comprueba que el collector pueda leer los archivos de registro:

cat /var/log/syslog | head -20

Verifique la conectividad de red con ClickStack:

# Probar el endpoint OTLP
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# Debería obtenerse una respuesta (incluso si hay un error, significa que el endpoint es accesible)

Compruebe los logs del collector para detectar errores:

# Si se ejecuta en primer plano
# Buscar mensajes de error en stdout

# Si se ejecuta como servicio systemd
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

Análisis incorrecto de los logs

Verifica el formato de syslog: Para Ubuntu 24.04+:

# Debe mostrar el formato ISO8601: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Para Amazon Linux 2 / Ubuntu 20.04:

# Debe mostrar el formato tradicional: Nov 17 14:16:16
tail -5 /var/log/messages

Si el formato no coincide, use la pestaña de configuración correspondiente en la sección Crear configuración del collector, según su distribución.

El collector no se inicia como servicio de systemd

Comprueba el estado del servicio:

sudo systemctl status otelcol-contrib

Ver logs detallados:

sudo journalctl -u otelcol-contrib -n 50

Problemas comunes:

API key mal configurada en el entorno
Errores de sintaxis en el archivo de configuración
Problemas de permisos al leer archivos de log

Próximos pasos

Configura alertas para eventos críticos del sistema (fallos del servicio, fallos de autenticación, advertencias sobre el disco)
Filtra por atributos de metadatos de EC2 (región, tipo de instancia, ID de instancia) para supervisar recursos específicos
Correlaciona el log de host de EC2 con los logs de la aplicación para una resolución de problemas más completa
Crea dashboards personalizados para la supervisión de seguridad (intentos de SSH, uso de sudo, bloqueos del firewall)

Paso a producción

Esta guía instala el OpenTelemetry Collector directamente en instancias de EC2, que es el patrón recomendado para producción en la monitorización a nivel de host. Para gestionar collectors en muchas instancias, considere usar herramientas de gestión de configuración (Ansible, Chef, Puppet) o el OpenTelemetry Operator en entornos de Kubernetes. Consulte Envío de datos de OpenTelemetry para la configuración de producción.

Funciones

Guías

Monitorización de logs de host de EC2 con ClickStack

Integración con una instancia de EC2 existente

Requisitos previos

Verifique que se pueda acceder a los metadatos de EC2

Verifique que existan archivos de syslog

Instalar OpenTelemetry Collector

Crear la configuración del collector

Configura la API key de ClickStack

Ejecuta el collector

Verificación de logs en HyperDX

Conjunto de datos de demostración

Descarga el conjunto de datos de ejemplo

Crear una configuración de prueba para el collector

Ejecutar ClickStack con la configuración de demostración

Verifica los logs en HyperDX

Paneles y visualización

la configuración del dashboard

Importa el dashboard preconfigurado

Ver el dashboard

Solución de problemas

Los metadatos de EC2 no aparecen en los logs

No se muestran logs en HyperDX

Análisis incorrecto de los logs

El collector no se inicia como servicio de systemd

Próximos pasos

Paso a producción

​Integración con una instancia de EC2 existente

Requisitos previos

​Verifique que se pueda acceder a los metadatos de EC2

​Verifique que existan archivos de syslog

​Instalar OpenTelemetry Collector

​Crear la configuración del collector

​Configura la API key de ClickStack

​Ejecuta el collector

​Verificación de logs en HyperDX

​Conjunto de datos de demostración

​Descarga el conjunto de datos de ejemplo

​Crear una configuración de prueba para el collector

​Ejecutar ClickStack con la configuración de demostración

​Verifica los logs en HyperDX

​Paneles y visualización

​ la configuración del dashboard

​Importa el dashboard preconfigurado

​Ver el dashboard

​Solución de problemas

​Los metadatos de EC2 no aparecen en los logs

​No se muestran logs en HyperDX

​Análisis incorrecto de los logs

​El collector no se inicia como servicio de systemd

​Próximos pasos

​Paso a producción

Integración con una instancia de EC2 existente

Verifique que se pueda acceder a los metadatos de EC2

Verifique que existan archivos de syslog

Instalar OpenTelemetry Collector

Crear la configuración del collector

Configura la API key de ClickStack

Ejecuta el collector

Verificación de logs en HyperDX

Conjunto de datos de demostración

Descarga el conjunto de datos de ejemplo

Crear una configuración de prueba para el collector

Ejecutar ClickStack con la configuración de demostración

Verifica los logs en HyperDX

Paneles y visualización

la configuración del dashboard

Importa el dashboard preconfigurado

Ver el dashboard

Solución de problemas

Los metadatos de EC2 no aparecen en los logs

No se muestran logs en HyperDX

Análisis incorrecto de los logs

El collector no se inicia como servicio de systemd

Próximos pasos

Paso a producción