monedula-sim-link connect

Snapshot a real Kafka cluster, read-only, and print a Kafka Simulator playground URL. Usage and flags for monedula-sim-link connect.

usage

monedula-sim-link connect --brokers host:port[,host:port...] [flags]

Connect to a real Kafka cluster, take a point-in-time snapshot and print a Kafka Simulator playground URL that visualizes it: brokers, topics, partition placement, failures, a sample of data volume, consumer groups and topic configs.

Strictly read-only. The only Kafka requests sent are ApiVersions, Metadata, ListOffsets, ListGroups, FindCoordinator, DescribeGroups, OffsetFetch and DescribeConfigs, plus DescribeProducers when you pass --producers. The Metadata request is sent with AllowAutoTopicCreation=false, so looking up a topic can never create it.

The URL is printed to standard output; warnings go to standard error. If the topic selection matches nothing, the command fails with a clear message instead of printing an empty visualization.

Read-only: this command does not change the cluster.

Flags

Flag	Type	Default	Description
`--brokers`	string		Comma-separated Kafka bootstrap brokers (host:port). Required.
`--topics`	string		Comma-separated exact topic names to include. Fails if any is missing. Listed topics are always kept when the selection is over the limit of 6 extra topics. Also the only way to include internal topics: topics the broker flags as internal, such as __consumer_offsets, and topics whose names start with an underscore.
`--topics-regex`	string		Additionally include non-internal topics matching this Go regular expression.
`--tls`	bool		Connect over TLS. Implied by --ca-cert, --client-cert and --client-key.
`--ca-cert`	string		PEM CA certificate file to trust, appended to the system trust pool. Implies --tls.
`--client-cert`	string		PEM client certificate file for mTLS. Implies --tls and needs --client-key.
`--client-key`	string		PEM client key file for mTLS. Implies --tls and needs --client-cert.
`--sasl-mechanism`	string		SASL mechanism: plain, scram-sha-256 or scram-sha-512.
`--username`	string		SASL username.
`--password`	string		SASL password. Prefer the MONEDULA_SIM_LINK_PASSWORD environment variable, which keeps the password out of shell history and process lists.
`--timeout`	duration	`15s`	Overall snapshot timeout.
`--clamp`	bool		When brokers or partitions exceed the simulator caps, or --topics lists more than 6 topics besides orders, trim deterministically with warnings instead of failing: the 10 lowest broker ids, partitions 0 to 23 of each topic and the 6 most eventful listed topics. More topics or consumer groups than the simulator shows never fail: the most eventful topics and the 4 consumer groups with the most lag are kept, with a warning.
`--producers`	bool		Also read the idempotent and transactional producers that wrote lately (DescribeProducers, which needs READ on each selected topic and Kafka 2.8+) and add up to 4 of them to the link. A producer that is neither never appears. A refused or unsupported read is a warning, never a failure.
`--producers-window`	duration	`15m0s`	With --producers: a producer is active when the record timestamp of its last write to a partition (the client's clock on CreateTime topics, the broker's on LogAppendTime) is within this long before the snapshot. Brokers keep producer state for producer.id.expiration.ms (24h by default), so a longer window shows nothing extra.
`--max-records-per-partition`	int	`8`	Cap on synthetic trailing records produced per partition.
`--base-url`	string	`https://monedula.dev/kafka-simulator/playground`	Playground base URL.
`--dry-run`	bool		Also print the decoded action list, name mappings and size param.
`--force`	bool		Emit the URL even when it exceeds the length limit (over-length links risk truncation).

Global flags

None.

Examples

examples

# Plaintext local cluster, all non-internal topics:
monedula-sim-link connect --brokers localhost:9092

# Exact topic names, a regex, or both:
monedula-sim-link connect --brokers localhost:9092 --topics orders,payments
monedula-sim-link connect --brokers localhost:9092 --topics-regex '^prod-'

# Internal topics only by exact name:
monedula-sim-link connect --brokers localhost:9092 --topics __consumer_offsets --clamp

# TLS and SCRAM-SHA-512, password from the environment:
export MONEDULA_SIM_LINK_PASSWORD='...'
monedula-sim-link connect \
  --brokers broker1.example.com:9093,broker2.example.com:9093 \
  --tls --ca-cert ./cluster-ca.pem \
  --sasl-mechanism scram-sha-512 --username viewer

# mTLS:
monedula-sim-link connect --brokers broker:9093 \
  --tls --ca-cert ca.pem --client-cert client.pem --client-key client.key

# Preview the size param, name tables and decoded actions:
monedula-sim-link connect --brokers localhost:9092 --dry-run

# Trim brokers and partitions over the simulator's limits:
monedula-sim-link connect --brokers localhost:9092 --clamp

# Also show the idempotent and transactional producers that wrote in the last 15 minutes (needs READ on the topics):
monedula-sim-link connect --brokers localhost:9092 --producers

# Look back an hour instead:
monedula-sim-link connect --brokers localhost:9092 --producers --producers-window 1h

# Point at a local playground dev server:
monedula-sim-link connect --brokers localhost:9092 \
  --base-url http://localhost:4321/kafka-simulator/playground

Exit codes

Code	Meaning
`0`	The URL was printed.
`1`	The snapshot or the URL build failed. The reason is printed to standard error.
`2`	Usage error: --brokers is missing, --producers-window is not positive, or a flag could not be parsed.