---
title: "See your cluster in the simulator"
description: "Start a local Kafka with Docker, run monedula-sim-link connect against it, and open the printed link to see your topics, records and consumer group."
url: https://monedula.dev/flock/docs/sim-link/tutorials/see-your-cluster-in-the-simulator/
---
## What you need

- `monedula-sim-link` on your `PATH`. The [install section](/flock/docs/sim-link/#install) shows how.
- Docker. The cluster runs from the `apache/kafka:4.3.1` image.

<Callout type="tip" title="No Docker?">

`monedula-sim-link demo --dry-run` feeds a built-in cluster fixture through the same pipeline, with no cluster at all. Its output has the same shape as the output in step 3, so you can follow the rest of the tutorial with it. [Preview a link before you share it](/flock/docs/sim-link/how-to/preview-with-dry-run/) explains that output line by line.

</Callout>

## 1. Start Kafka

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```text
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:

```text
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`:

```bash
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](/flock/docs/sim-link/concepts/what-the-link-shows/) covers each approximation.

## 6. Check that nothing changed

`connect` sent only read requests ([the read-only guarantee](/flock/docs/sim-link/concepts/read-only-guarantee/) lists them). The topic list still holds only the two topics you created:

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

```text
orders
payments
```

## 7. Clean up

```bash
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](/flock/docs/sim-link/how-to/connect-to-a-secured-cluster/) uses the same command against a cluster with TLS and SASL.
- [Choose which topics to show](/flock/docs/sim-link/how-to/choose-topics/) 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](/flock/docs/sim-link/how-to/connect-to-a-secured-cluster/#4-allow-reading-the-topics-for-producers-optional)).
- The [`connect` command reference](/flock/docs/sim-link/reference/cli/connect/) lists every flag.