AgentsIQ

📊 Kafka Analyser

Kafka cluster health monitoring, consumer lag detection, broker metrics and anomaly intelligence agent

v1.1.0 Internal FastAPI + PostgreSQL Updated 2026-07-16 Port 8003

Real-time Monitoring

Consumer lag, broker metrics (CPU, heap, GC), topic throughput (msg/sec), partition counts, and replica sync status.

6 Data Sources

Synthetic, Real Kafka (bootstrap), Prometheus JMX, Schema Registry, ZooKeeper, KafkaConnect, MirrorMaker replication tracking.

5 AI Tools

cluster_overview, consumer_lag, broker_metrics, topic_metrics, detect_anomalies with Claude tool-use loop.

Technical Architecture

Stack

  • Compute: FastAPI (Python 3.11) on AgentsIQ platform (port 8003)
  • Storage: PostgreSQL (cluster config, metrics history, anomalies, connectors)
  • In-memory: kafka_store (current cluster snapshot, consumer groups, topics, brokers)
  • Data Sources: Real Kafka, Synthetic generator, Prometheus JMX, Schema Registry, ZooKeeper, KafkaConnect, MirrorMaker
  • Optional backends: Redis (cache), Vector DB (embeddings), Neo4j (graph topology) — configured via env

Data Flow

🌐 Browser (VPN)
→
Portal (nginx)
→
Backend
→
Kafka Analyser (8003)
Real Kafka / Prometheus
→
kafka_store snapshot
→
Claude tool-use loop
→
Response

Database Schema

PostgreSQL Tables

kafka_clusters
id
INTEGER (PK)
agent_slug
VARCHAR
name
VARCHAR
environment
VARCHAR
bootstrap_servers
VARCHAR
auth_type
VARCHAR (none/sasl/tls)
sasl_username
VARCHAR (encrypted)
sasl_password
VARCHAR (encrypted)
tls_enabled
BOOLEAN
schema_registry_url
VARCHAR
zookeeper_url
VARCHAR
kafka_connect_url
VARCHAR
status
VARCHAR (active/inactive)
created_at
TIMESTAMP
kafka_broker_metrics
id
INTEGER (PK)
time
TIMESTAMP
cluster_id
INTEGER (FK)
broker_id
INTEGER
heap_pct
DECIMAL (0-100)
gc_pause_ms
DECIMAL
request_handler_idle_pct
DECIMAL
urp_count
INTEGER
cpu_pct
DECIMAL
disk_pct
DECIMAL
kafka_consumer_lag
id
INTEGER (PK)
time
TIMESTAMP
cluster_id
INTEGER (FK)
group_name
VARCHAR
topic
VARCHAR
partition
INTEGER
lag
INTEGER
consumer_offset
INTEGER
log_end_offset
INTEGER
group_state
VARCHAR
kafka_topic_metrics
id
INTEGER (PK)
time
TIMESTAMP
cluster_id
INTEGER (FK)
topic
VARCHAR
partition_count
INTEGER
replication_factor
INTEGER
messages_in_per_sec
DECIMAL
bytes_in_per_sec
DECIMAL
bytes_out_per_sec
DECIMAL
size_bytes
INTEGER
retention_pct
DECIMAL
kafka_anomalies
id
INTEGER (PK)
cluster_id
INTEGER (FK)
detected_at
TIMESTAMP
severity
VARCHAR (critical/warning)
category
VARCHAR
description
TEXT
resolved_at
TIMESTAMP (nullable)
kafka_connector_status
id
INTEGER (PK)
time
TIMESTAMP
cluster_id
INTEGER (FK)
connector_name
VARCHAR
connector_type
VARCHAR (source/sink)
state
VARCHAR (running/failed/paused)
failed_tasks
INTEGER
total_tasks
INTEGER

Dashboard Features

📌 Overview

Cluster health score, broker status summary, URP count, active anomalies, consumer lag trend chart.

👥 Consumer Groups

All groups sorted by lag (worst-first), lag trend (growing/stable/recovering), messages/min, group state.

📝 Topics

Topic throughput (msg/sec, bytes in/out), retention usage %, partition count, replication factor, history.

🖥️ Brokers

Per-broker CPU%, heap%, GC pause ms, request handler idle%, URP count, disk%, metrics trend.

🔗 KafkaConnect

Connector status (running/failed/paused), failed task count, connector type (source/sink), state history.

🗃️ Schema Registry

Schema versions, compatibility levels per subject, schema evolution tracking, subject listing.

🌳 ZooKeeper

ZooKeeper node health, leader election status, broker registration state, config changes.

↔️ MirrorMaker

Cross-cluster replication lag, checkpoint offsets, mirror mode (active/passive), replication rate.

🤖 AI Insights

Anomaly detection (critical/warning severity), remediation steps, chat Q&A with tool-use, pattern learning.

What's Working vs Planned

Feature Status Notes
Synthetic data generation ✓ Working Demo/testing mode with realistic broker, consumer, topic metrics
Real Kafka cluster connection ✓ Working Bootstrap servers, SASL/TLS auth, dynamic broker discovery
Consumer lag monitoring ✓ Working Real-time lag, trend detection (growing/stable/recovering)
Broker metrics collection ✓ Working CPU, heap, GC pause, URP, request handler idle%, disk%
Topic throughput monitoring ✓ Working Messages/sec, bytes in/out, retention %, partition/replication tracking
Anomaly detection engine ✓ Working High GC pause, URP spikes, consumer lag breach, broker degradation
KafkaConnect status ✓ Working Connector state, failed task tracking, task count per connector
Schema Registry integration ✓ Working Schema versions, compatibility modes, subject tracking
ZooKeeper health monitoring ✓ Working Node health, leader election, broker registration
MirrorMaker replication lag ✓ Working Checkpoint offset tracking, replication rate, lag trend
AI tool-use loop (5 functions) ✓ Working cluster_overview, consumer_lag, broker_metrics, topic_metrics, detect_anomalies
PostgreSQL metrics history ✓ Working Time-series storage for trend analysis beyond real-time
Prometheus JMX integration ⏳ Planned Collector exists, wiring to kafka_store pending
Vector/RAG knowledge base ⏳ Planned Embeddings for anomaly pattern matching, historical context
Graph topology (Neo4j) ⏳ Planned Broker → topic → consumer group DAG visualization
Automated remediation (Action Agent) ⏳ Planned Trigger remediation steps (rebalance, pause connector, etc.)
Multi-cluster comparison ⏳ Planned Side-by-side lag/throughput comparison across clusters
Alert escalation to Teams ⏳ Planned Via shared escalation notifier (incident_management integration)

Key Business Outcomes

  • Reduces MTTR: Consumer lag trends surfaced before SLA breach; anomaly alerts on GC spikes, URP growth.
  • Unified interface: 6 data sources (Kafka, Prometheus, Schema Registry, ZK, KafkaConnect, MirrorMaker) in one place — no tool-switching.
  • Early detection: Broker degradation (high GC%, URP, heap) caught in real-time; historical trends enable trend-based alerting.
  • PostgreSQL history: Long-term metrics enable root-cause analysis beyond real-time dashboards.
  • 7-source support: Synthetic, Real Kafka, Prometheus JMX, Schema Registry, ZooKeeper, KafkaConnect, MirrorMaker — flexible deployment.
  • AI chat: 5 tool-use functions enable operators to ask natural-language questions about cluster health without leaving the chat.