See your cluster in the simulator

What you need

• monedula-sim-link on your PATH. The install section shows how.
• Docker. The cluster runs from the apache/kafka:4.3.1 image.

1. Start Kafka

docker run -d --rm --name sim-link-tutorial -p 9092:9092 apache/kafka:4.3.1

The image starts one broker that listens on localhost:9092. Give it a few seconds, then wait until this command succeeds. It prints nothing yet, because the cluster has no topics:

docker exec sim-link-tutorial /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --list

2. Put some data on it

Create the topics orders, with three partitions, and payments, with two:

docker exec sim-link-tutorial /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --create --topic orders --partitions 3
docker exec sim-link-tutorial /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --create --topic payments --partitions 2

Produce five records to orders and two to payments:

printf 'o1\no2\no3\no4\no5\n' | docker exec -i sim-link-tutorial \
  /opt/kafka/bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 --topic orders
printf 'p1\np2\n' | docker exec -i sim-link-tutorial \
  /opt/kafka/bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 --topic payments

Read two of the five orders records as the consumer group analytics, so that the group commits an offset and then lags behind the end of the topic:

docker exec sim-link-tutorial /opt/kafka/bin/kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 --topic orders --group analytics \
  --from-beginning --max-messages 2

3. Preview the link

--topics names the topics to show and --dry-run prints what the link is made of before it prints the link:

monedula-sim-link connect --brokers localhost:9092 --topics orders,payments --dry-run

The output looks like this. The URL is shortened here, and the key letters in the P: lines can differ on your machine, because they depend on which partitions the console producer picked:

size: 1x3x1xpayments~2~1~1~d~604800000~~~xxxxxxxxxx~~604800000~~
brokers:
  1 -> broker-1
topics:
  orders -> orders
  payments -> payments
groups:
  analytics -> analytics
actions (15 entries):
  RP:p1@500
  RG:c1@750
  AP:kp1:orders@1000
  P:kp1:orders:a@1250
  P:kp1:orders:c@1500
  P:kp1:orders:d@1750
  P:kp1:orders:i@2000
  P:kp1:orders:j@2250
  RP:kp1@4250
  AP:kp2:payments@4500
  P:kp2:payments:a@4750
  P:kp2:payments:b@5000
  RP:kp2@7000
  AG:analytics:orders@7250
  C:group.analytics.consumer.autoOffsetReset:earliest@7500

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

Read it from the top:

• size is the cluster shape: one broker, then the orders topic with 3 partitions and replication factor 1, then payments with 2 partitions, replication factor 1, min.insync.replicas 1, the delete cleanup policy and the topic’s retention. The tail of the line is the config of orders itself. It carries the retention only: its min.insync.replicas and cleanup policy are the simulator’s defaults, so the link leaves them out.
• The brokers, topics and groups tables map each real name to the name the simulator shows. Here they are identical, except that the broker with id 1 becomes broker-1.
• The actions list is replayed on the simulator’s clock. It removes the playground’s template producer and consumer group, adds a short-lived producer for each topic and produces one record for each of your seven records, then adds the analytics group.

The last action sets analytics to auto.offset.reset=earliest. The group has read only two of five records, and the link cannot carry its exact offset, so it drains the synthetic backlog from the start. The tool warns about this on standard error, in a plain connect run too:

warning: group analytics has ~3 records of committed-offset lag across its rendered partitions; approximating with auto.offset.reset=earliest so it visibly drains the topic's synthetic backlog (exact offsets are not carried)

4. Get the link

Run the same command without --dry-run:

monedula-sim-link connect --brokers localhost:9092 --topics orders,payments

It prints only the link, on standard output. Open it in a browser.

5. Look at the result

The session shows broker-1. orders takes the place of the simulator’s fixed primary topic, with 3 partitions, and payments is an extra topic with 2. Your seven records are replayed as synthetic keyed records on their real partitions, because the tool never reads keys or values. analytics drains its backlog. What the link shows covers each approximation.

6. Check that nothing changed

connect sent only read requests (the read-only guarantee lists them). The topic list still holds only the two topics you created:

docker exec sim-link-tutorial /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --list

orders
payments

7. Clean up

docker stop sim-link-tutorial

The --rm flag you gave to docker run removes the container when it stops.

Next steps

• Connect to a secured cluster uses the same command against a cluster with TLS and SASL.
• Choose which topics to show covers exact names, regular expressions and internal topics.
• Add --producers to the command in step 4, within 15 minutes of step 2, to see who wrote. The console producers are idempotent in this Kafka version, so the broker knows them, and the link gains an AP:pid-<producerId>:<topic> entry for each. A secured cluster needs READ on the topics for it (Connect to a secured cluster).
• The connect command reference lists every flag.