uGroup - Kafka Consumer Group Monitor

uGroup monitors Kafka consumer groups by reading the __consumer_offsets topic and calculating/reporting consumer lag metrics.

Features

• Real-time consumer lag monitoring - Track offset lag across all partitions
• Prometheus metrics export - Native integration with Prometheus via Micrometer
• Flexible filtering - Monitor all consumers, specific groups via YAML, or regex patterns
• Blocklist support - Exclude noisy or test consumer groups
• REST API - Query lag data programmatically
• Docker support - Easy deployment with Docker Compose
• Extensible architecture - Plug in custom implementations for metrics, caching, and cluster discovery

Quick Start

Using Docker Compose

cd docker
docker compose up -d

This starts Kafka, Zookeeper, and uGroup. Point uGroup at any consumer group running against the same broker and lag will appear at http://localhost:8080.

Using Gradle

# Build
./gradlew build

# Run with local Kafka
KAFKA_BOOTSTRAP_SERVERS=localhost:9092 ./gradlew bootRun

Usage

Query lag via REST

# Lag for every topic a group consumes
curl http://localhost:8080/api/v1/lag/my-consumer-group

# Lag for one group/topic pair
curl http://localhost:8080/api/v1/lag/my-consumer-group/events-topic

# Liveness / status
curl http://localhost:8080/api/v1/status

Scrape lag with Prometheus

uGroup exposes metrics at /actuator/prometheus. Example PromQL for the worst-lagging group in each cluster:

max by (cluster, group) (ugroup_consumer_lag)

See the Metrics wiki page for the full metric and label reference.

Common scenarios

uGroup decides which groups to monitor via UGROUP_WATCHLIST_MODE. Pick the mode that fits your use case and see the linked wiki page for the YAML/regex details.

Monitor every consumer group in the cluster — zero config, useful for ops dashboards:

UGROUP_WATCHLIST_MODE=all ./gradlew bootRun

Monitor a curated list — declare the exact groups + topics you care about in a YAML file (see watchlist-sample.yaml and the Watchlist wiki page):

UGROUP_WATCHLIST_MODE=static UGROUP_WATCHLIST_FILE=/etc/ugroup/watchlist.yaml ./gradlew bootRun

Monitor by regex with a blocklist — useful when group names follow a naming convention but a few should be excluded (see the Blocklist wiki page):

UGROUP_WATCHLIST_MODE=regex \
  UGROUP_INCLUDE_PATTERNS='prod-.*' \
  UGROUP_BLOCKLIST_FILE=/etc/ugroup/blocklist.yaml \
  ./gradlew bootRun

For the full list of environment variables and their defaults, see the Configuration wiki page.

Documentation

Full documentation is available on the Wiki:

• Configuration - Environment variables and application.yml
• API Endpoints - REST API reference
• Watchlist Configuration - Static and regex filtering
• Blocklist Configuration - Excluding consumer groups
• Extending uGroup - Custom implementations
• Metrics - Prometheus metrics reference
• Building - Build and test commands
• Architecture - System architecture overview
• Contributing - How to contribute

License

Apache License 2.0 - see LICENSE for details.