Monitoreo de logs de Kafka con ClickStack

Monitoreo de logs de Kafka con ClickStack

En resumen

Recopila y visualiza los logs del broker de Kafka (formato Log4j) en ClickStack mediante el receptor filelog de OTel. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.

​

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

1. ​

   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:

   # Ubicaciones predeterminadas
   ls $KAFKA_HOME/logs/      # Apache Kafka estándar (por defecto en <install-dir>/logs/)
   ls /var/log/kafka/        # Instalaciones de paquetes RPM/DEB
   

   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)
   

   Para despliegues de Kafka basados en Docker (por ejemplo, confluentinc/cp-kafka), la configuración predeterminada de Log4j solo incluye un appender de consola; no hay ningún appender de archivo, por lo que los logs se escriben únicamente en stdout. Para usar el receiver filelog, tendrás que redirigir los logs a un archivo, ya sea añadiendo un appender de archivo a log4j.properties o redirigiendo stdout mediante una tubería (por ejemplo, | tee /var/log/kafka/server.log).

2. ​

   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  # opcional, solo existe si log4j está configurado con appenders de archivo independientes
         - /var/log/kafka/state-change.log  # opcional, igual que el caso anterior
       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
   

   • En la configuración personalizada, solo defines nuevos receivers y pipelines. Los processors (memory_limiter, transform, batch) y exporters (clickhouse) ya están definidos en la configuración base de ClickStack; solo los referencias por nombre.
   • La configuración multiline garantiza que las trazas de pila se capturen como una sola entrada de registro.
   • Esta configuración usa start_at: beginning para leer todos los logs existentes cuando se inicia el collector. En implementaciones de producción, cámbialo a start_at: end para evitar volver a ingestar los logs cuando el collector se reinicie.
3. ​

   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:

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

   Docker Compose

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

   Docker Run (imagen todo en uno)

   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
   

   Asegúrate de que el collector de ClickStack tenga los permisos adecuados para leer los archivos de log de Kafka. En producción, usa montajes de solo lectura (:ro) y sigue el principio de privilegio mínimo.

4. ​

   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.

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

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

   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:

   1. Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una cuenta)
   2. Ve a la vista Search y establece la fuente en Logs
   3. 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

1. ​

   la configuración del dashboard

2. ​

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

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

   El dashboard se creará con todas las visualizaciones preconfiguradas

   Para el dataset 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 amplía el OpenTelemetry Collector integrado de ClickStack para facilitar 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.