Monedula
monedula-sim-link docs menu

What the link shows

What a monedula-sim-link link contains and leaves out: shape, placement, failures, data volume, groups, configs, producers, and what stays local.

Concepts 2 of 3

3 min read

Updated 16 October 2026

Markdown

On this page

The link is a free-play session rebuilt from one read-only snapshot. Some parts of the cluster carry over exactly, some are approximated, and some never leave your machine. The mapping reference has the exact rules.

  • Cluster shape. The broker count, and the selected topics with their real partition counts and replication factors, in the free-play size parameter.
  • Replica placement. A partition whose real assignment differs from the simulator’s default gets a reassign_partition action. The rest add nothing to the link.
  • Failures. A broker that is offline, or missing from the metadata, is killed in the session. A broker that is assigned to a partition but out of its in-sync replicas is slowed, so it drops out of the ISR in the session too.
  • Data volume. Up to --max-records-per-partition synthetic records per partition (default 8), each keyed through the simulator’s own partitioner hash so that it lands on the partition it stands for.
  • Consumer groups. Each group with a committed offset on a selected topic, with up to 4 of its members. A lagging group starts from the earliest offset, so it shows a backlog. With more than 4 such groups, the 4 with the most lag are shown (Handle large clusters). The playground’s own template group c1 is removed, so a fake consumer does not sit beside your groups, even when your cluster has none.
  • Topic configs. cleanup.policy, min.insync.replicas, retention.ms and retention.bytes, in the size parameter.
  • Producers, only with --producers. Up to 4 of the idempotent and transactional producers that wrote to a shown topic in the last 15 minutes (--producers-window changes that), each named pid-<producerId> and pinned to the topic it wrote to on most partitions. The playground’s auto-loop keeps writing from them. This is a sample of who writes, not a list: see the limits below.

What it approximates or leaves out

  • Exact offsets. The link shows the relative fill of each partition, and the simulator’s offsets start at 0.
  • A lagging group’s real offset. The link shows only that the group is behind.
  • The real leader. The simulator elects its own, usually the first surviving in-sync replica.
  • The controller, the KRaft quorum layout and broker racks. The simulator boots its own quorum.
  • Record contents. The records are synthetic, with searched keys and no values.
  • Live traffic. The link replays one point-in-time snapshot.
  • Producers that are not idempotent or transactional. A producer with enable.idempotence=false and no transaction has no producer id on the broker, so --producers cannot see it, however busy it is.
  • Producer settings and transactions. The broker does not report acks, linger or batching, so every producer in the link has the simulator’s defaults (acks=all, idempotence on). The link cannot express a transactional producer, so one with an open transaction is shown as an idempotent one, with a warning.
  • Old and quiet producers. A broker keeps a producer’s state only for producer.id.expiration.ms (24 hours by default), so a longer window shows nothing extra, and a restarted application is a new producer id. Recent is judged by the record timestamp of the last batch, which is the producing client’s clock on CreateTime topics and the broker’s on LogAppendTime topics, so a producer that stamps event time can look idle however recently it wrote.

What stays on your machine

connect talks only to your cluster. These stay on the machine where you ran it:

  • Credentials. Passwords, certificates and keys are used only to open the connection to your brokers.
  • Broker addresses. The link names brokers broker-1 to broker-N. The table that maps them to your real broker ids is printed by --dry-run and is not in the link.
  • Record data. The tool never reads the keys or values of your records, as the read-only guarantee explains.

What does go into the link is the cluster’s topology: the broker count, the names of the shown topics, as renamed by the simulator’s rules, their partition counts, replication factors and selected configs, the names of consumer groups and member names derived from the client ids of their members, with --producers the producer ids of up to 4 recent writers, and the failures. Treat the link as containing those names when you share it, and use --topics to show only the topics you are happy to share.