# Exercise 02 — Keys and partitions: where your records actually land

**VERIFIED** 2026-11-21 — CLI part and Java lesson both run against Kafka
3.9.0; observed output in `../VERIFICATION.md` §2.

**Time:** ~45 min · **Prerequisites:** Exercise 01; JDK 25 present for the
Java part (Maven comes via `./mvnw`).

## The situation

Order events for one customer must arrive in the order they happened.
Marketing says "Kafka keeps order" — true, with a scope so narrow it should
be printed on the box. Today you find that scope by watching the hash place
your records.

## Predict first

1. Records with the **same key** sent to a 3-partition topic: same
   partition every time? Could anything ever split them?
2. Two *different* keys — can they land on the same partition?
3. Five unkeyed records sent in one quick burst: how will they spread
   across partitions?

## The experiment — CLI (working directory: `kafka-lab`)

**1. A 3-partition topic:**

```bash
scripts/k kafka-topics.sh --create --topic course.keys \
  --partitions 3 --replication-factor 3
# Created topic "course.keys".
```

**2. Five keyed records** (`parse.key` + `:` separator; three of them share
the key `customer-alice`):

```bash
printf 'customer-alice:order-1\ncustomer-bob:order-2\ncustomer-alice:order-3\ncustomer-carol:order-4\ncustomer-alice:order-5\n' | \
  scripts/k kafka-console-producer.sh --topic course.keys \
  --property parse.key=true --property key.separator=:
```

**3. Read the placement** — partition number printed per record:

```bash
scripts/k kafka-console-consumer.sh --topic course.keys \
  --from-beginning --timeout-ms 5000 \
  --property print.partition=true --property print.key=true \
  --property key.separator=' : '
```

**4. Unkeyed burst** (12 records, one pipe, no keys — you will reuse this
topic in Exercise 03):

```bash
scripts/k kafka-topics.sh --create --topic course.groups \
  --partitions 6 --replication-factor 3
for i in $(seq 1 12); do echo "task-$i"; done | \
  scripts/k kafka-console-producer.sh --topic course.groups
scripts/k kafka-console-consumer.sh --topic course.groups \
  --from-beginning --timeout-ms 4000 --property print.partition=true
```

## The experiment — Java (the producer's own math)

The lab's producer lesson predicts placements **client-side** before
sending, then reports where each record actually landed:

```bash
scripts/run.sh lab.ProducerLesson
```

Watch section `02 · keys decide partitions (and only keys keep order)` — the
lesson prints `murmur2(key) % 6` predictions and observed `partition @
offset` per record — and section `04 · a custom partitioner`, where a rule
instead of a hash routes `vip-*` keys to partition 0.

## Expected observations

- In step 3, every `customer-alice` record is on the **same partition**
  (verified run: Partition:0, three times). `customer-bob` sits on another
  one (verified: Partition:2) — and `customer-carol` **collides** onto
  alice's partition: different keys *can* share a partition.
- In step 4, expect a surprise: the verified run put **all 12** unkeyed
  records on **one** partition. That is not a bug — since Kafka 3.3 the
  default partitioner batches unkeyed records onto a single "sticky"
  partition and rotates it lazily (KIP-794). Spread only appears across
  larger volumes or multiple batches. Check your output: if your burst
  spread, ask which side of the sticky behavior you saw.
- In the Java lesson, prediction and placement agree line for line
  (`amy → partition 0`, offsets incrementing per partition, `bill` and
  `dmitri` colliding on partition 3).

## Understanding checks

1. State the ordering guarantee so narrowly it cannot be misread. ("Records
   with the same key land on the same partition; a partition is a single
   ordered log; therefore per-key order — and nothing else.")
2. Alice and carol share a partition. Whose ordering does that threaten —
   alice's, carol's, or neither?
3. Your five keyed records: which two facts would you need before you could
   predict placement yourself (algorithm + partition count)?
4. The unkeyed burst on one partition: when does that become a *problem*
   rather than a curiosity?

## Hints

- The guarantee is about **keys**, not topics. Re-count which records in
  step 3 share a key before blaming the hash.
- The client does the math. Where would you look in the producer's code to
  change placement without touching the broker? (The lesson's section 04
  answers it by doing it.)
- For the unkeyed surprise: the records were sent as **one batch**. What
  would a partitioner optimized for throughput do with one small batch?

## Troubleshooting

- `--property print.partition=true` prints nothing — `../TROUBLESHOOTING.md` §3.
- `scripts/run.sh` fails to compile — `../TROUBLESHOOTING.md` §4 (JDK version).
- Producer hangs after the last line — it is waiting for stdin EOF; the
  `printf`/`for` pipe closes it automatically; interactive typing needs
  `Ctrl-D`.

## Verification

You are done when you can show from your own run:

1. All three `customer-alice` records on one partition (step 3 output).
2. The Java lesson's `02` section where predicted and observed placements
   match.
3. One sentence naming the partitioner behavior behind the unkeyed burst
   (and the KIP number).

## Solution (open after your attempt)

→ [`../solutions/02-keys-and-partitions.md`](../solutions/02-keys-and-partitions.md)
