Monedula
monedula-sim-link docs menu

Preview a link before you share it

Use --dry-run to read the size parameter, the real-to-simulator name tables and the decoded action list that a monedula-sim-link link is made of.

How-to guides 4 of 6

3 min read

Updated 16 October 2026

Markdown

On this page

Before you start

  • monedula-sim-link installed. No cluster is needed: demo runs a built-in fixture through the same pipeline, and --dry-run works on it too.

Steps

1. Run with --dry-run

monedula-sim-link demo --dry-run

For your own cluster, add --dry-run to the connect command you already use. The output below is from demo, whose fixture is a four-broker cluster with an orders topic and a payments topic:

size: 4x3x3xpayments~1~2~1~d~~~~
brokers:
  1 -> broker-1
  2 -> broker-2
  3 -> broker-3
  4 -> broker-4
topics:
  orders -> orders
  payments -> payments
actions (19 entries):
  RP:p1@500
  RG:c1@750
  RA:orders:2:broker-3.broker-1.broker-2@1000
  K:broker-4@1250
  SR:broker-2:1@1500
  AP:kp1:orders@1750
  P:kp1:orders:b@2000
  P:kp1:orders:e@2250
  P:kp1:orders:k@2500
  P:kp1:orders:n@2750
  P:kp1:orders:o@3000
  P:kp1:orders:f@3250
  P:kp1:orders:g@3500
  RP:kp1@5500
  AP:kp2:payments@5750
  P:kp2:payments:a@6000
  P:kp2:payments:b@6250
  P:kp2:payments:c@6500
  RP:kp2@8500

https://monedula.dev/kafka-simulator/playground?scenario=free&actions=RP%3Ap1%40500%2C...&size=4x3x3xpayments~1~2~1~d~~~~

Warnings go to standard error, so they do not mix with this output. In this run there is one, about broker 2 being out of the in-sync replicas of orders partition 2.

2. Read the size line

size is the cluster shape, in the form <brokers>x<partitions>x<replication factor>, followed by one segment for each extra topic. Here that is 4 brokers and the orders topic with 3 partitions and replication factor 3, then payments with 1 partition, replication factor 2, min.insync.replicas 1 and the delete cleanup policy. The mapping reference describes the segments.

3. Check the name tables

Each table maps a real name to the name the simulator shows:

  • brokers: the simulator numbers brokers broker-1 to broker-N in the order of the real ids, so this table tells you which real broker each simulator broker stands for.
  • topics: a name the simulator cannot carry, such as billing.events, is renamed (naming rules), and each rename also prints a warning.
  • groups: the consumer groups that made it into the link. A group is absent when it has no committed offset on a shown topic, or when it was not among the 4 groups kept (Handle large clusters). The table appears only when there is at least one group.

4. Read the action list

The actions list is what the playground replays on its simulated clock. Each entry is <action>@<milliseconds>. The tool starts at t=500 ms and spaces the actions 250 ms apart, except that a synthetic producer is removed 2 seconds after its last record. These are the actions in the output above:

Entry What it does Why it is there
RP:p1@500 Removes the free-play template producer p1. So the playground does not add traffic of its own on top of the data in the link.
RG:c1@750 Removes the free-play template consumer group c1, with its member. So a fake consumer does not sit beside the real groups. It is there even when the cluster has no group.
RA:orders:2:broker-3.broker-1.broker-2@1000 Reassigns the replicas of orders partition 2 to those brokers. The real placement of that partition differs from the simulator’s default. A partition on the default placement emits nothing.
K:broker-4@1250 Kills broker-4. In the fixture, broker 4 is offline.
SR:broker-2:1@1500 Slows the follower replication of broker-2. broker-2 is in the replica list of a partition but out of its in-sync replicas.
AP:kp1:orders@1750 Adds a short-lived producer kp1 for the topic orders. It carries the synthetic records.
P:kp1:orders:b@2000 Produces one record with the key b to orders. One record of the data-volume sample. The key was chosen so that the record lands on the intended partition.
RP:kp1@5500 Removes the producer kp1, two seconds after its last record. At most one synthetic producer is alive at a time.

A consumer group adds more entries: AG:analytics:orders@7250 adds a group on a topic, AC: lines join its members, and C:group.analytics.consumer.autoOffsetReset:earliest@7500 makes a lagging group start from the earliest offset. With --producers, one AP:pid-<producerId>:<topic> entry per producer comes last: monedula-sim-link demo --producers --dry-run ends with AP:pid-1001:orders@8750 and AP:pid-1002:payments@9000, and prints a warning for the second, which wrote from inside an open transaction. The mapping reference explains each family of actions. A long action list makes a long link; Handle large clusters covers the action and length limits.

When the tables look right, run the same command without --dry-run. It prints only the link.