Saltar al contenido principal
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)
1

​
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.
2

​
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
3

​
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
4

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

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
5

​
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
6

​
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.
7

​
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:
  1. Ve a la vista de búsqueda
  2. Establece source en Logs
  3. Filtra por source:ec2-host-logs
  4. Haz clic en una entrada de log para expandirla
  5. 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.
1

​
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
2

​
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.
3

​
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
4

​
Verifica los logs en HyperDX

Una vez que el collector esté en ejecución:
  1. Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una cuenta)
  2. Ve a la vista de búsqueda y establece el source en Logs
  3. Establece el intervalo de tiempo en 2025-11-10 00:00:00 - 2025-11-13 00:00:00
  4. Filtra por source:ec2-demo
  5. 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.
1

​
la configuración del dashboard

2

​
Importa el dashboard preconfigurado

  1. Abre HyperDX y ve a la sección Dashboards
  2. Haz clic en Import Dashboard en la esquina superior derecha, en el menú de los tres puntos
  1. Sube el archivo host-logs-dashboard.json y haz clic en Finish Import
3

​
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.
Última modificación el 10 de junio de 2026