Monitorización de logs de host de EC2 con ClickStack

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

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

# Verify instance metadata
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

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

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

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

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages

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

# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version

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

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

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

Inicia el OpenTelemetry Collector:

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

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

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

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:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  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

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

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

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

Descargar el archivo de configuración del dashboard.

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

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

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