Monitoreo de logs de Kafka con ClickStack

Integración con Kafka existente

Esta sección explica cómo configurar una instalación existente de Kafka para enviar los logs del broker a ClickStack modificando la configuración del OTel collector de ClickStack. Si desea probar la integración de logs de Kafka antes de configurar su propio entorno, puede hacerlo con nuestra configuración preconfigurada y datos de ejemplo en la sección "conjunto de datos de demostración".

Requisitos previos

Instancia de ClickStack en funcionamiento
Instalación existente de Kafka (versión 2.0 o posterior)
Acceso a los archivos de registro de Kafka (server.log, controller.log, etc.)

Verifique la configuración de logging de Kafka

Kafka usa Log4j y escribe los logs en el directorio especificado por la propiedad del sistema kafka.logs.dir o la variable de entorno LOG_DIR. Compruebe la ubicación de su archivo de log:

# Default locations
ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
ls /var/log/kafka/        # RPM/DEB package installations

Principales archivos de registro de Kafka:

server.log: Registros generales del broker (inicio, conexiones, replicación, errores)
controller.log: Eventos específicos del controlador (elección del líder, reasignación de particiones)
state-change.log: Transiciones de estado de particiones y réplicas

El patrón predeterminado de Log4j de Kafka genera líneas como:

[2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)

Cree una configuración personalizada del OTel collector para Kafka

ClickStack le permite ampliar la configuración base de OpenTelemetry Collector montando un archivo de configuración personalizado y definiendo una variable de entorno. La configuración personalizada se combina con la configuración base administrada por HyperDX mediante OpAMP.

Cree un archivo llamado kafka-logs-monitoring.yaml con la siguiente configuración:

receivers:
  filelog/kafka:
    include:
      - /var/log/kafka/server.log
      - /var/log/kafka/controller.log  # optional, only exists if log4j is configured with separate file appenders
      - /var/log/kafka/state-change.log  # optional, same as above
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

      - type: move
        from: attributes.message
        to: body

      - type: add
        field: attributes.source
        value: "kafka"

      - type: add
        field: resource["service.name"]
        value: "kafka-production"

service:
  pipelines:
    logs/kafka:
      receivers: [filelog/kafka]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Configura ClickStack para cargar una configuración personalizada

Para habilitar una configuración personalizada del collector en tu despliegue actual de ClickStack, debes hacer lo siguiente:

Montar el archivo de configuración personalizado en /etc/otelcol-contrib/custom.config.yaml
Establecer la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar el directorio de logs de Kafka para que el collector pueda leerlos

Actualiza la configuración de despliegue de ClickStack:

services:
  clickstack:
    # ... configuración existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... otras variables de entorno ...
    volumes:
      - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/kafka:/var/log/kafka:ro
      # ... otros volúmenes ...

Si estás usando la imagen todo en uno con Docker, ejecuta:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/kafka:/var/log/kafka:ro \
  clickhouse/clickstack-all-in-one:latest

Verificar los logs en HyperDX

Una vez completada la configuración, inicia sesión en HyperDX y verifica que los logs se estén recibiendo:

Conjunto de datos de demostración

Prueba la integración de logs de Kafka con un conjunto de datos de ejemplo pregenerado antes de configurar tus sistemas de producción.

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/kafka/server.log

Crea la configuración del collector de prueba

Crea un archivo llamado kafka-logs-demo.yaml con la siguiente configuración:

cat > kafka-logs-demo.yaml << 'EOF'
receivers:
  filelog/kafka:
    include:
      - /tmp/kafka-demo/server.log
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

      - type: move
        from: attributes.message
        to: body

      - type: add
        field: attributes.source
        value: "kafka-demo"

      - type: add
        field: resource["service.name"]
        value: "kafka-demo"

service:
  pipelines:
    logs/kafka-demo:
      receivers: [filelog/kafka]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Ejecuta ClickStack con la configuración de demostración

Ejecuta ClickStack con los logs de demostración y esta configuració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)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verifica los logs en HyperDX

Una vez que ClickStack 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 Search y establece la fuente en Logs
Ajusta el intervalo de tiempo para que incluya 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

Dashboards y visualización

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importar 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 tres puntos.

Sube el archivo kafka-logs-dashboard.json y haz clic en Finalizar importación.

Finalizar la importación del dashboard de logs de Kafka

El dashboard se creará con todas las visualizaciones preconfiguradas

Para el conjunto de datos de demostración, establece el intervalo de tiempo para incluir 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

Solución de problemas

Verifica que la configuración efectiva incluya tu receptor filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Compruebe si hay errores en el collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log

Verifique que el formato de los logs de Kafka coincida con el patrón esperado:

tail -1 /var/log/kafka/server.log

Si tu instalación de Kafka usa un pattern de Log4j personalizado, ajusta la regex de regex_parser según corresponda.

Siguientes pasos

Configura alertas para eventos críticos (fallos del broker, errores de replicación, problemas con el grupo de consumidores)
Combínalo con Métricas de Kafka para una monitorización integral de Kafka
Crea dashboards adicionales para casos de uso específicos (eventos del controlador, reasignación de particiones)

Puesta en producción

Esta guía utiliza el OpenTelemetry Collector integrado de ClickStack para una configuración rápida. Para implementaciones en producción, recomendamos ejecutar su propio OTel Collector y enviar los datos al endpoint OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para la configuración de producción.