Events, Commands, and Record Anatomy

In one line

A Kafka record has a key, a value, a timestamp, headers, and (once written) a topic, partition and offset. Designing good records starts with the difference between events ("something happened"), commands ("please do this") and generic messages, which shapes naming, ownership, retries and schema evolution.

0/5 · 0%

Think of it like this

A newspaper report ("the bridge closed at 9 am") versus a manager's instruction ("close the bridge"). Many people can react to the report in their own way; the instruction has one intended recipient who must act, and someone expects a result.

Key ideas

01
Record anatomy: key (bytes, used for partitioning and compaction, often an entity ID), value (the payload), timestamp (CreateTime set by the producer, or LogAppendTime set by the broker, per topic), headers (key-value metadata: trace IDs, schema version, event type, correlation IDs), plus topic, partition and offset assigned on write.
02
Events are facts in the past tense: OrderCreated, PaymentCaptured. The producer owns them, doesn't know who consumes them, and they're immutable. Many consumers react independently.
03
Commands are requests in the imperative: ReserveInventory, SendEmail. They target one handler that owns the action, often expect a reply event (InventoryReserved / InventoryRejected), and retry semantics matter more.
04
Event design: include what consumers need to act without calling back (event-carried state transfer) versus a thin notification with an ID (consumers fetch details). Fat events decouple but duplicate data and grow schemas; thin events are small but create read load on the source service.
05
Always include an event ID (for deduplication), the entity ID (usually also the key), an occurred-at time, and a schema version. Put tracing and routing metadata in headers so the payload stays clean.

Code & diagrams

record.mermaiddiagram

Rendering diagram…

OrderCreated.jsonjson

{
  "eventId": "7f1c9e2a-5b6d-4a31-9c1e-2d8f7b3a6e10",
  "eventType": "OrderCreated",
  "schemaVersion": 2,
  "occurredAt": "2026-09-28T10:15:02.113Z",
  "orderId": "order-9",
  "customerId": "cust-42",
  "items": [{ "sku": "sku-7", "qty": 2, "unitPrice": 649.00 }],
  "total": 1298.00,
  "currency": "INR"
}

Interview problem

The problem

Event or command?

For an e-commerce flow, classify and name the Kafka records: the order service accepting an order, asking inventory to hold stock, inventory confirming the hold, and asking the notification service to email the customer. Explain ownership and retries for each.

The interviewer follows up

Should you use CreateTime or LogAppendTime?

Explain it without notes

What fields should every event carry, and why?

Practice

Design the record (key, headers, value fields) for PaymentCaptured.

Trade-offs

↔
Fat events reduce coupling and callbacks but duplicate data; thin events are cheaper but increase load on source services.

Done when you can

I can describe every part of a Kafka record.
I can distinguish events from commands and design event payloads.

Command Palette