Surveillance et alertes Kafka avec exemples pratiques

Intro

La surveillance Kafka n’est utile que si elle aide un opérateur à répondre rapidement à trois questions : qu’est-ce qui est cassé, qui est touché, et quelle action est sûre maintenant. Un tableau de bord rempli de graphiques sur l’utilisation du processeur des brokers ne suffit pas. Il faut des métriques de santé des brokers, des signaux sur les topics et les partitions, le lag des consommateurs, la latence des requêtes, ainsi que des règles d’alerte qui indiquent une réponse précise.

Ce guide suppose un cluster Apache Kafka de type production surveillé avec JMX (Java Management Extensions) : mécanisme Java d’exposition de métriques et d’opérations de gestion, Prometheus et Grafana. Les exemples utilisent des espaces réservés comme <bootstrap-server> et <consumer-group>. Remplacez-les par les valeurs de votre environnement, mais ne collez pas d’identifiants, de jetons ou de noms d’hôtes privés dans des runbooks partagés.

L’objectif est pratique : de vrais noms de métriques JMX, des seuils d’alerte utilisables comme point de départ, des vérifications en ligne de commande et un scénario d’incident où un groupe de consommateurs prend du retard pendant le redémarrage d’un broker. Les seuils doivent toujours être ajustés après observation des profils de trafic normaux, mais les exemples ci-dessous sont volontairement concrets afin que les équipes puissent mettre en place une première version utile au lieu de débattre de catégories abstraites de surveillance.

Inventaire des versions et de l’environnement

Avant de modifier les alertes, relevez la version de Kafka, la topologie de déploiement, la source des exporteurs et les groupes de consommateurs importants pour l’activité. Les métriques Kafka varient selon la version du broker, la configuration de l’exporteur et le mode d’exécution, ZooKeeper ou KRaft.

Commencez par des vérifications en lecture seule :

kafka-broker-api-versions.sh --bootstrap-server <bootstrap-server>:9092

Confirmez la liste des brokers et l’état du contrôleur :

kafka-metadata-quorum.sh --bootstrap-server <bootstrap-server>:9092 describe --status

Si le cluster utilise encore ZooKeeper, la commande KRaft peut ne pas s’appliquer. Dans ce cas, documentez séparément l’ensemble ZooKeeper et confirmez quel broker joue le rôle de contrôleur via JMX ou les outils de votre plateforme.

Consignez ces éléments d’inventaire :

• Version de Kafka et mode utilisé par le cluster : KRaft ou ZooKeeper.
• Nombre de brokers, racks ou zones de disponibilité, et facteur de réplication des topics critiques.
• Paramètres de réplicas synchrones minimaux pour les topics critiques côté producteurs, en particulier min.insync.replicas.
• Chemin de surveillance : JMX exporter sur chaque broker, Kafka exporter pour le lag des consommateurs, ou les deux.
• Groupes de consommateurs critiques, service propriétaire, débit de pointe attendu et fenêtre de lag acceptable.

Noms d’objets JMX utiles à confirmer :

kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions
kafka.server:type=ReplicaManager,name=OfflineReplicaCount
kafka.controller:type=KafkaController,name=ActiveControllerCount
kafka.controller:type=ControllerStats,name=LeaderElectionRateAndTimeMs
kafka.server:type=BrokerTopicMetrics,name=MessagesInPerSec
kafka.server:type=BrokerTopicMetrics,name=BytesInPerSec
kafka.server:type=BrokerTopicMetrics,name=BytesOutPerSec
kafka.network:type=RequestMetrics,name=TotalTimeMs,request=Produce
kafka.network:type=RequestMetrics,name=TotalTimeMs,request=FetchConsumer

Pour les consommateurs Java qui exposent JMX, relevez aussi ces métriques côté client :

kafka.consumer:type=consumer-fetch-manager-metrics,client-id=<client-id>,name=records-lag-max
kafka.consumer:type=consumer-fetch-manager-metrics,client-id=<client-id>,name=records-consumed-rate
kafka.consumer:type=consumer-coordinator-metrics,client-id=<client-id>,name=commit-rate
kafka.consumer:type=consumer-coordinator-metrics,client-id=<client-id>,name=rebalance-rate-per-hour

Cet inventaire n’est pas une formalité administrative. Il évite les fausses alertes, identifie les exporteurs manquants et indique à l’ingénieur d’astreinte si une hausse de lag touche un service de reporting batch ou un parcours d’autorisation de paiement.

Chemin de configuration sécurisé

Ajoutez la surveillance par couches. Exposez d’abord les métriques, construisez ensuite les tableaux de bord, puis activez les alertes. Évitez d’activer un grand paquet d’alertes sans avoir confirmé les noms de métriques et les niveaux de référence normaux.

Une configuration Prometheus courante utilise JMX exporter pour les métriques de brokers. Selon vos règles d’exporteur, les noms JMX peuvent apparaître sous forme de métriques Prometheus comme :

kafka_server_replicamanager_underreplicatedpartitions
kafka_server_replicamanager_offlinereplicacount
kafka_controller_kafkacontroller_activecontrollercount
kafka_network_requestmetrics_totaltimems
kafka_server_brokertopicmetrics_messagesin_total

Vérifiez que Prometheus collecte bien les métriques de chaque broker :

curl -s http://<prometheus-host>:9090/api/v1/targets | grep -E "kafka|broker"

Interrogez ensuite directement une métrique clé :

curl -G http://<prometheus-host>:9090/api/v1/query \
  --data-urlencode 'query=sum(kafka_server_replicamanager_underreplicatedpartitions)'

Pour le lag des consommateurs, beaucoup d’équipes utilisent des métriques Kafka exporter similaires à :

kafka_consumergroup_lag
kafka_consumergroup_current_offset
kafka_topic_partition_current_offset

Confirmez que le lag est visible pour un groupe connu :

curl -G http://<prometheus-host>:9090/api/v1/query \
  --data-urlencode 'query=sum by (consumergroup, topic) (kafka_consumergroup_lag{consumergroup="<consumer-group>"})'

Un premier tableau de bord Grafana sûr devrait contenir ces panneaux :

• Partitions sous-répliquées : sum(kafka_server_replicamanager_underreplicatedpartitions)
• Réplicas hors ligne : sum(kafka_server_replicamanager_offlinereplicacount)
• Contrôleurs actifs : sum(kafka_controller_kafkacontroller_activecontrollercount)
• Latence p95 ou p99 des requêtes Produce à partir des métriques de requêtes, si des buckets d’histogramme ou des résumés sont disponibles.
• Octets entrants et sortants par broker.
• Lag des consommateurs par groupe de consommateurs et par topic.
• Tendance du lag des consommateurs avec deriv(kafka_consumergroup_lag[10m]).

Gardez la première version limitée. Un tableau de bord qui met en évidence la réplication, la santé du contrôleur, le trafic, la latence et le lag est plus utile pendant un incident que vingt panneaux sans chemin de réponse.

Vérification et diagnostics

Utilisez des règles d’alerte assez spécifiques pour réduire le bruit, mais assez sensibles pour détecter une vraie dégradation. Les règles Prometheus suivantes constituent un point de départ pratique pour un cluster de production de taille moyenne. Elles peuvent aussi être utilisées comme expressions d’alertes gérées par Grafana si votre instance Grafana évalue des requêtes Prometheus.

groups:
  - name: kafka-alerts
    rules:
      - alert: KafkaUnderReplicatedPartitions
        expr: sum(kafka_server_replicamanager_underreplicatedpartitions) > 0
        for: 10m
        labels:
          severity: warning
          service: kafka
        annotations:
          summary: "Kafka a des partitions sous-répliquées"
          description: "Des partitions sous-répliquées sont au-dessus de 0 depuis 10 minutes. Vérifiez la santé des brokers, les événements de réduction de l’ISR et la saturation réseau."

      - alert: KafkaOfflineReplicas
        expr: sum(kafka_server_replicamanager_offlinereplicacount) > 0
        for: 2m
        labels:
          severity: critical
          service: kafka
        annotations:
          summary: "Kafka a des réplicas hors ligne"
          description: "Un ou plusieurs réplicas sont hors ligne. La disponibilité des données peut être réduite pour les partitions touchées."

      - alert: KafkaControllerCountInvalid
        expr: sum(kafka_controller_kafkacontroller_activecontrollercount) != 1
        for: 5m
        labels:
          severity: critical
          service: kafka
        annotations:
          summary: "Le nombre de contrôleurs actifs Kafka n’est pas 1"
          description: "Un seul contrôleur actif est attendu sur l’ensemble du cluster. Examinez une instabilité de broker ou de quorum."

      - alert: KafkaConsumerGroupLagHigh
        expr: |
          sum by (consumergroup, topic) (
            kafka_consumergroup_lag{consumergroup!~"console-consumer-.*"}
          ) > 50000
          and
          sum by (consumergroup, topic) (
            deriv(kafka_consumergroup_lag{consumergroup!~"console-consumer-.*"}[10m])
          ) > 0
        for: 10m
        labels:
          severity: warning
          service: kafka
        annotations:
          summary: "Le lag d’un groupe de consommateurs Kafka est élevé et augmente"
          description: "Le groupe de consommateurs {{ $labels.consumergroup }} sur le topic {{ $labels.topic }} a un lag supérieur à 50000 et continue de prendre du retard."

      - alert: KafkaConsumerGroupLagCritical
        expr: |
          sum by (consumergroup, topic) (
            kafka_consumergroup_lag{consumergroup!~"console-consumer-.*"}
          ) > 250000
        for: 5m
        labels:
          severity: critical
          service: kafka
        annotations:
          summary: "Le lag d’un groupe de consommateurs Kafka est critique"
          description: "Le groupe de consommateurs {{ $labels.consumergroup }} sur le topic {{ $labels.topic }} a un lag supérieur à 250000 depuis 5 minutes."

Les seuils de lag des consommateurs doivent refléter le temps, pas seulement le nombre de messages. Si un topic traite normalement 10 000 messages par seconde, un lag de 50 000 représente seulement cinq secondes. Si un autre topic traite 100 messages par seconde, le même lag représente plus de huit minutes. Utilisez d’abord des seuils en nombre de messages, puis affinez-les par topic lorsque vous connaissez le débit normal.

Pendant les diagnostics, comparez le lag Prometheus avec la sortie de la ligne de commande Kafka :

kafka-consumer-groups.sh \
  --bootstrap-server <bootstrap-server>:9092 \
  --describe \
  --group <consumer-group>

Exemple de sortie :

GROUP           TOPIC            PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG     CONSUMER-ID  HOST        CLIENT-ID
payments-api    payments.events  0          8934201         8979201         45000   consumer-1   /10.0.4.21  payments-1
payments-api    payments.events  1          7721009         7811009         90000   consumer-2   /10.0.4.22  payments-2

Si le lag est élevé mais n’augmente pas, les consommateurs sont peut-être déjà en train de récupérer. Si le lag est élevé et continue d’augmenter, vérifiez les erreurs des consommateurs, la latence de la base de données en aval, l’activité de rééquilibrage et l’existence d’un nombre suffisant de partitions pour faire évoluer le groupe.

Modes de défaillance et reprise

Incident réaliste : un cluster à trois brokers est en cours de redémarrage progressif. Le broker broker-2 redémarre plus lentement que prévu après une mise à jour de paquet. Les producteurs continuent d’écrire dans payments.events, mais le groupe de consommateurs payments-api commence à prendre du retard.

Les alertes indiquent :

WARNING KafkaUnderReplicatedPartitions
sum(kafka_server_replicamanager_underreplicatedpartitions) = 18 for 10m

WARNING KafkaConsumerGroupLagHigh
consumergroup="payments-api", topic="payments.events"
lag = 132000, deriv over 10m > 0

CRITICAL KafkaConsumerGroupLagCritical
consumergroup="payments-api", topic="payments.events"
lag = 278000 for 5m

Première réponse :

1. Arrêtez le redémarrage progressif. Ne redémarrez pas un autre broker tant que des partitions sont sous-répliquées.
2. Confirmez la santé des brokers et la visibilité du cluster :

kafka-broker-api-versions.sh --bootstrap-server <bootstrap-server>:9092

1. Listez les partitions sous-répliquées :

kafka-topics.sh \
  --bootstrap-server <bootstrap-server>:9092 \
  --describe \
  --under-replicated-partitions

1. Vérifiez le groupe de consommateurs touché :

kafka-consumer-groups.sh \
  --bootstrap-server <bootstrap-server>:9092 \
  --describe \
  --group payments-api

1. Vérifiez si le groupe de consommateurs se rééquilibre de façon répétée. Si JMX côté client est disponible, inspectez rebalance-rate-per-hour et commit-rate. Un taux de commit faible ou nul pendant que le lag augmente signifie généralement que les consommateurs sont bloqués, plantent ou sont freinés par une dépendance en aval.

Décisions de reprise sûres :

• Si broker-2 est encore en cours de démarrage, attendez qu’il rejoigne le cluster avant de modifier les affectations de partitions.
• Si les consommateurs sont sains mais sous-dimensionnés, augmentez le déploiement des consommateurs seulement jusqu’au nombre de partitions du topic.

kubectl scale deployment payments-api-consumer \
  --namespace <namespace> \
  --replicas=8

• Si les consommateurs échouent parce qu’une base de données en aval est lente, le redimensionnement peut aggraver l’incident. Réduisez l’ingestion ou corrigez d’abord la dépendance en aval.
• Ne réinitialisez pas les offsets pour sauter des messages, sauf si le propriétaire de l’application accepte explicitement une perte de données ou si la sémantique de rejeu est bien comprise.

La reprise est vérifiée lorsque ces signaux sont vrais :

sum(kafka_server_replicamanager_underreplicatedpartitions) = 0
sum(kafka_server_replicamanager_offlinereplicacount) = 0
sum by (consumergroup, topic) (deriv(kafka_consumergroup_lag[10m])) < 0 pour payments-api/payments.events
KafkaConsumerGroupLagCritical est résolue

Après la reprise, documentez le retard de redémarrage, le lag maximal, le temps nécessaire pour rattraper le retard, le fait que les consommateurs aient été redimensionnés ou non, et la nécessité éventuelle d’allonger la pause entre deux brokers dans les procédures de redémarrage.

Liste de contrôle opérationnelle

Utilisez cette liste pour l’exploitation quotidienne et la préparation aux incidents :

• Confirmer que chaque broker est collecté par Prometheus et visible dans Grafana.
• Déclencher une alerte lorsque les partitions sous-répliquées restent au-dessus de 0 pendant 10 minutes.
• Déclencher rapidement une alerte lorsque les réplicas hors ligne restent au-dessus de 0 pendant 2 minutes.
• Déclencher une alerte lorsque le nombre de contrôleurs actifs n’est pas exactement 1 pendant 5 minutes.
• Surveiller le lag des consommateurs par consumergroup et topic, pas seulement comme total du cluster.
• Ajouter des seuils de lag distincts, avertissement et critique, pour les groupes critiques métier.
• Suivre la direction du lag avec deriv(kafka_consumergroup_lag[10m]) ; un lag élevé mais en baisse est différent d’un lag élevé et en hausse.
• Garder dans le runbook une commande de diagnostic en ligne de commande pour chaque alerte.
• Pendant la maintenance des brokers, suspendre le déploiement si des partitions sous-répliquées apparaissent et ne se résorbent pas.
• Vérifier la reprise avec des métriques, pas seulement avec le redémarrage réussi d’un service.

Pour les tableaux de bord, privilégiez les panneaux qui répondent à des questions opérationnelles. Par exemple, affichez les 10 principaux groupes de consommateurs par lag, les principaux topics par octets entrants, la latence des requêtes par broker et les partitions sous-répliquées dans un grand panneau statistique unique. Placez les panneaux critiques en haut afin qu’un ingénieur d’astreinte comprenne l’impact en moins d’une minute.

Conclusion

La surveillance et les alertes Kafka sont efficaces lorsqu’elles relient les métriques aux décisions. Les signaux les plus importants sont la santé de la réplication, la santé du contrôleur, la latence des requêtes broker, le débit et le lag des consommateurs par groupe et par topic. Les graphiques génériques de processeur et de mémoire peuvent soutenir le diagnostic, mais ils ne doivent pas être la seule source d’alerte.

Commencez avec des métriques JMX concrètes, vérifiez les noms Prometheus produits par vos exporteurs et utilisez des règles d’alerte avec des seuils explicites, par exemple des partitions sous-répliquées au-dessus de 0 pendant 10 minutes ou un lag de consommateurs supérieur à 50 000 et toujours en hausse. Ajustez ensuite ces valeurs selon le trafic réel et la tolérance métier.

La meilleure réponse à un incident Kafka est calme et observable : arrêter les changements risqués, confirmer l’état des brokers et des partitions, comparer le lag de Prometheus avec la sortie de la ligne de commande Kafka, redimensionner les consommateurs seulement lorsque c’est sûr, et vérifier que le lag diminue avant de fermer l’incident.