@oh-my-tool/kafka

Read-only Kafka inspection for Oh My Tool.

It supports multi-broker clusters, TLS, SASL/PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, consumer lag, 64-bit-safe offsets, and bounded message sampling.

Install

ohmytool extension install @oh-my-tool/kafka

For local development:

npm ci
npm run check
ohmytool extension install .

Configure

Connections use the shared Oh My Tool Generic Connection format.

PLAINTEXT

[extensions.kafka.connections.local]
environment = "dev"

[extensions.kafka.connections.local.settings]
brokers = ["localhost:9092"]
clientId = "oh-my-tool"
securityProtocol = "plaintext"

SASL over TLS

Store secret values using the Oh My Tool secret command, then reference their names from the connection:

ohmytool secret set kafka:prod:password
ohmytool secret set kafka:prod:ca

[extensions.kafka.connections.prod]
environment = "prod"

[extensions.kafka.connections.prod.settings]
brokers = ["kafka-1.example.com:9093", "kafka-2.example.com:9093"]
clientId = "oh-my-tool"
securityProtocol = "sasl_ssl"
saslMechanism = "scram-sha-512"
username = "observer"
tlsRejectUnauthorized = true
connectionTimeoutMs = 5000
requestTimeoutMs = 30000

[extensions.kafka.connections.prod.secrets]
password = "kafka:prod:password"
ca = "kafka:prod:ca"

For mutual TLS, configure both cert and key secret slots. A lone cert or key is rejected. Supported securityProtocol values are plaintext, ssl, sasl_plaintext, and sasl_ssl.

Tools

| Tool | Purpose | | --- | --- | | kafka.instances | List sanitized configured clusters without connecting | | kafka.ping | Return cluster id, controller, and brokers | | kafka.topics | List topics with internal-topic filtering and a hard limit | | kafka.offsets | Show earliest/latest offsets for a topic | | kafka.groups | List consumer groups with a hard limit | | kafka.lag | Calculate per-partition and total consumer lag | | kafka.peek | Read a bounded message sample without committing offsets |

Examples:

ohmytool run kafka.ping connection=prod
ohmytool run kafka.topics connection=prod maxTopics=100
ohmytool run kafka.offsets connection=prod topic=orders
ohmytool run kafka.lag connection=prod groupId=order-workers topic=orders
ohmytool run kafka.peek connection=prod topic=orders maxMessages=20 maxBytes=1048576 timeoutMs=5000

Offsets and lag values are returned as decimal strings so values above JavaScript's safe integer range remain exact.

Bounded peek behavior

kafka.peek creates a unique oh-my-tool-peek-* consumer group, disables automatic commits, and does not resolve or commit consumed offsets. It stops at the first of these limits:

• maxMessages: default 20, maximum 100
• maxBytes: default 1 MiB, maximum 10 MiB
• timeoutMs: default 5 seconds, maximum 30 seconds

Because Kafka's public consumer protocol requires group coordination, the Kafka principal needs permission to join the generated group as well as read the topic. The group is transient, but it may remain visible in Kafka until normal group retention removes it.

Message key, value, and header bytes are returned as UTF-8 when conversion is lossless; otherwise they are Base64 with an explicit encoding field.

Safety

Every tool is read-only. This extension does not produce messages, create or delete topics, change configuration, delete groups, commit offsets, or reset consumer positions. Secret names and values are never returned in tool results or client error messages.