kafka-perf-review

name	kafka-perf-review
description	Review Kafka producer and consumer performance configurations in both the live cluster (via Lenses MCP) and the codebase. Flags un-tuned defaults, anti-patterns and missing best practices. Use when user says "review Kafka performance", "check producer configs", "tune Kafka settings" or asks about throughput, batching or compression. Do NOT use for cluster sizing or capacity planning.
license	MIT
allowed-tools	Read, Grep, Glob, Bash, mcp__Lenses__get_topic, mcp__Lenses__get_topic_broker_configs, mcp__Lenses__get_topic_partitions, mcp__Lenses__get_dataset_message_metrics
argument-hint	[required: environment name] [optional: path to scan, defaults to src/]
compatibility	Recommended - the Lenses MCP server (lenses-mcp) connected and configured with a valid environment. Any Kafka MCP that exposes an equivalent tool surface (list_topics, list_consumer_groups, etc.) will also work; without an MCP server, the skill falls back to codebase-only inspection and skips live-cluster checks.
metadata	{"author":"Tun Shwe","version":"1.0.0","mcp-server":"lenses-mcp","category":"mcp-enhancement","approach":"tool-first","patterns":"context-aware-selection, domain-intelligence","tags":["kafka","performance","tuning","producers","consumers"]}

Kafka Performance Configuration Review

Reviews producer and consumer configurations in both the live cluster and the codebase for performance anti-patterns. These settings are the same across all Kafka client libraries (they're Kafka protocol properties).

Target environment and path: $ARGUMENTS (defaults to src/ for codebase scan if path not specified)

Workflow

Copy this checklist and track your progress:

Performance Review Progress:
- [ ] Step 1: Inspect live cluster configs
- [ ] Step 2: Scan codebase for producer/consumer configs
- [ ] Step 3: Audit producer configs
- [ ] Step 4: Audit consumer configs
- [ ] Step 5: Cross-reference cluster and code configs
- [ ] Step 6: Generate report

1. Inspect live cluster configs via Lenses MCP
2. Scan codebase for producer/consumer config properties (see references/producer-defaults.md and references/consumer-defaults.md)
3. Audit producer configs against recommended values
4. Audit consumer configs against recommended values
5. Cross-reference cluster and code configs
6. Report findings with current values, recommended values and trade-off explanations

Step 1: Live Cluster Inspection

Use Lenses MCP tools to check cluster-side performance configs:

• get_topic - topic-level configs affecting performance (min.insync.replicas, compression.type, max.message.bytes)
• get_topic_broker_configs - broker-level configs (message.max.bytes, replica.fetch.max.bytes, num.io.threads)
• get_topic_partitions - message distribution across partitions (detect skew where one partition has significantly more bytes than others)
• get_dataset_message_metrics - message throughput over time to identify bottlenecks or capacity headroom

Expected output: Topic-level performance configs, partition distribution and throughput metrics.

Validation: If MCP calls fail, proceed with codebase-only analysis and note the limitation in the report.

Step 2: Codebase Inspection

Search the codebase for Kafka producer and consumer configuration properties. Consult references/producer-defaults.md for the full list of producer properties and references/consumer-defaults.md for consumer properties.

Also search for anti-patterns listed in references/producer-defaults.md:

• Synchronous produce calls (.get(), .result(), flush() after every send)
• Missing delivery callbacks / error handlers
• Missing graceful shutdown / rebalance listeners

Step 3: Audit Producer Configs

Compare found producer configs against the recommended values in references/producer-defaults.md. Key areas: acks, batch.size, linger.ms, compression.type, enable.idempotence and retries.

Step 4: Audit Consumer Configs

Compare found consumer configs against the recommended values in references/consumer-defaults.md. Key areas: max.poll.records, max.poll.interval.ms, auto.offset.reset, enable.auto.commit and fetch.min.bytes.

Success Criteria

Quantitative

• Triggers on 90% of performance-related queries (test with 10-20 varied phrasings)
• Completes review in under 15 tool calls (MCP + codebase search)
• 0 failed MCP calls per run

Qualitative

• Every finding shows current value, recommended value and trade-off explanation
• Anti-patterns are identified with file and line references
• Estimated throughput impact (low/medium/high) is consistently calibrated

Examples

Example 1: Routine performance review

User says: "Review Kafka performance configs for staging"

Actions:

1. Inspect cluster-side configs for all topics in staging
2. Scan src/ for producer/consumer property definitions
3. Cross-reference code configs against reference tables Result: Report with per-property findings and throughput impact estimates

Example 2: Investigating slow consumers

User says: "Why are my consumers slow? Check the performance settings."

Actions:

1. Focus on consumer config properties in the codebase
2. Check max.poll.records, fetch.min.bytes and enable.auto.commit
3. Look for anti-patterns like synchronous processing Result: Targeted report on consumer-side bottlenecks with remediation steps

Example 3: Scoped codebase review

User says: "Check Kafka configs in src/kafka/ for the production environment"

Actions:

1. Scan only src/kafka/ for producer and consumer configs
2. Cross-reference with live production cluster settings Result: Focused report on a specific directory's Kafka configurations

Troubleshooting

No Kafka config properties found in codebase

Cause: The codebase may use a framework or wrapper that hides raw Kafka properties. Solution: Search for framework-specific config patterns (e.g., Spring Boot application.yml, Django settings). Report the framework used and suggest manual review.

Lenses MCP returns no topic data

Cause: Environment name is incorrect or Lenses agent is offline. Solution: Run check_environment_health first. Verify the environment name matches what list_environments returns.

Partition skew detection is inconclusive

Cause: Topic has very low throughput so byte counts are similar across partitions. Solution: Note that skew detection requires meaningful throughput. For low-volume topics, skip the skew check and note it in the report.

Output Format

## Performance Review Report

### Cluster-Side Findings
- [topic-name] {property}: {current value}
  Recommendation: {recommended value} - {explanation}

### Codebase Findings (Producers)
- [file:line] {property} = {current value}
  Recommendation: {recommended value} - {explanation}

### Codebase Findings (Consumers)
- [file:line] {property} = {current value}
  Recommendation: {recommended value} - {explanation}

### Anti-Patterns
- [file:line] Description of the anti-pattern
  Recommendation: How to fix it

### Summary
- X producer issues found
- Y consumer issues found
- Z anti-patterns found
- Estimated throughput impact: low/medium/high