Path 3 · lesson 5 of 5
A working Spring Boot producer, and what its settings change
Build a small order service that publishes keyed events with KafkaTemplate and handles the send result, then change its settings and see what moves: throughput or reliability.
What you will learn
- Build a Spring Boot service that publishes a keyed JSON event with KafkaTemplate and reports the outcome to its caller
- Handle both ways a send can fail: an exception thrown by send() and a future that completes exceptionally
- Set producer configuration through spring.kafka.producer.* and know which defaults come from Spring Boot and which from the Kafka client
- Predict whether a configuration change affects throughput, latency, durability, duplicates or ordering
- Recognise when publishing an event together with a database write needs an outbox instead of a direct send
Before you start
The concept
This lesson puts the producer path together as one small service. POST /orders accepts an order, publishes an OrderPlaced event to the topic orders.placed keyed by the order id, waits for the broker's acknowledgement and answers the caller according to what happened. It is the first step of the example project, reduced to the producer.
With spring-kafka on the classpath, Spring Boot creates the pieces for you from spring.kafka.* properties: a ProducerFactory that owns the Kafka producer, a KafkaTemplate that sends through it, and a KafkaAdmin that creates any NewTopic beans at startup. You inject KafkaTemplate and call send. By default the factory creates one producer shared by all threads, which is what the Kafka client recommends and what makes batching work.
| Decision | Choice in this service | Why |
|---|---|---|
| Record key | orderId | All events about one order go to one partition and stay in order relative to each other |
| Value format | JSON via JsonSerializer, no type headers | Readable and simple; consumers in other services must not depend on this service's Java class name |
| Acknowledgement | acks=all with idempotence | An acknowledged order event survives a broker failure, and the producer's own retries do not create duplicates or reorder |
| Outcome | Wait for the future with a timeout | The HTTP response must not claim success for an event that was never stored |
| Time bounds | max.block.ms 5 s, delivery.timeout.ms 30 s | A request thread must never be held for the one-minute and two-minute defaults |
| Batching | linger.ms 10, lz4 | A small wait that a checkout can afford; set explicitly because the client default differs between versions |
Why it exists
A producer that appears to work takes one line: kafkaTemplate.send("orders.placed", event). In a demo the record arrives. The problems are in what that line leaves undecided.
- No key. Events for the same order are spread over partitions, so a consumer can see
OrderCancelledbeforeOrderPlaced. - No outcome.
sendreturns a future immediately. If nobody looks at it, a failed send leaves only a log line from the template's defaultLoggingProducerListener. The HTTP caller was already told the order was accepted. - No time bound. With defaults, a send can block the calling thread for up to a minute waiting for metadata or buffer space, and a record can stay undecided for two minutes.
- No stated configuration. The behaviour is whatever the client version's defaults are, and those have changed across versions.
- No plan for the database. As soon as the order is also saved to a database, sending directly creates two writes that can disagree.
None of these is advanced. They are the difference between an example and a service you can run, and each has a small, concrete answer in the code below.
How it works inside
What happens inside one send
KafkaTemplate.send(topic, key, value)builds aProducerRecordand obtains the shared producer from theProducerFactory.- On the calling thread, the producer serialises the key (
StringSerializer) and the value (JsonSerializer), chooses the partition from the hash of the key, and appends the record to that partition's open batch. If metadata is missing or the buffer is full, this is where the thread waits, for at mostmax.block.ms. sendreturns aCompletableFuture<SendResult<K, V>>. Nothing has reached a broker yet.- The producer's sender thread sends the batch. With
acks=allthe partition leader answers once the replicas that are in sync at that moment have the batch. - The producer's callback runs on the sender thread and completes the future: with a
SendResult(the record and itsRecordMetadata: partition and offset) or exceptionally. Functions attached withwhenCompleterun there too.
The ways a send fails
| Where | Examples | How it reaches you | Is the record in Kafka? |
|---|---|---|---|
| Before buffering | The value cannot be serialised | send throws on the calling thread | No |
| Waiting to buffer | Topic metadata unavailable, or buffer full for max.block.ms | The send fails with a TimeoutException (BufferExhaustedException for a full buffer) | No |
| Rejected by the broker | RecordTooLargeException, authorisation failure | Future completes exceptionally at once; these are not retried | No |
| Retries run out of time | Leader unavailable or too few in-sync replicas for longer than delivery.timeout.ms | Future completes exceptionally with a TimeoutException | Normally no, but a request whose response was lost may have been appended |
| Your own wait ends first | future.get(5, SECONDS) times out | java.util.concurrent.TimeoutException from get | Unknown: the producer is still trying |
The last two rows are the ones that need thought. A timeout is not a clean failure. The honest response to the caller is “not confirmed, try again”, and the design must then tolerate the same order being submitted twice.
What to do when a send fails
| Kind of event | Reasonable reaction | Cost |
|---|---|---|
| The request is meaningless without it (this service) | Fail the request and let the caller retry with the same id | Availability of the endpoint now depends on Kafka |
| Must never be lost, and belongs to a database change | Do not send directly: write it to an outbox table in the same database transaction | An outbox table and a relay or CDC connector to operate |
| Useful but not essential (metrics, clickstream) | Count the failure and drop the event | Some data loss during incidents, by decision |
What each setting changes
| Change | Throughput and latency | Reliability |
|---|---|---|
acks=all to acks=1 | Slightly lower produce latency: the leader no longer waits for followers | Acknowledged records can be lost if the leader fails before followers copy them. Also conflicts with idempotence |
acks=0 | Lowest latency; nothing is awaited | No acknowledgement, no retries, the returned offset is always -1. Loss is silent |
| Idempotence off, retries on, up to 5 in flight | No meaningful gain | Retries can write a batch twice and can put a later batch before an earlier one |
linger.ms 0 to 10 to 100 | Fewer, fuller requests and better compression; each record may wait that much longer at low traffic | Unchanged |
compression.type none to lz4 or zstd | Fewer bytes on the network and on disk for some CPU; depends on batch fill | Unchanged |
delivery.timeout.ms lower | Failures are reported sooner | Less time to ride out a leader election before the send fails |
acks=all is a durability guarantee only together with the topic's replication factor and min.insync.replicas. With replication factor 3 and min.insync.replicas=2, an acknowledged record is on at least two brokers, and one broker can fail without loss or loss of write availability. With min.insync.replicas=1, acks=all can be satisfied by the leader alone.
Architecture
Drawing diagram…
A flowchart of the order service. An HTTP client calls OrderController, which calls OrderEventPublisher, which uses KafkaTemplate. Spring Boot creates the template, a DefaultKafkaProducerFactory with one shared KafkaProducer, and a KafkaAdmin. The producer serialises, batches per partition and its sender thread writes to the topic orders.placed, which payment and inventory consumer groups read. A NewTopic bean is created on the cluster by KafkaAdmin.
flowchart LR
Client["HTTP client"] --> Ctl["OrderController"]
Ctl --> Pub["OrderEventPublisher"]
Pub --> Tpl["KafkaTemplate"]
subgraph Boot["Created by Spring Boot from spring.kafka properties"]
Tpl --> PF["DefaultKafkaProducerFactory"]
PF --> KP["One shared KafkaProducer"]
Adm["KafkaAdmin"]
end
KP --> Ser["StringSerializer for the key, JsonSerializer for the value"]
Ser --> Buf["Per-partition batches"]
Buf --> Snd["Sender thread"]
Snd --> Topic["Topic orders.placed, 6 partitions, replication factor 3"]
Topic --> Pay["Payment service consumer group"]
Topic --> Inv["Inventory service consumer group"]
Cfg["KafkaTopicConfig declares a NewTopic bean"] --> Adm
Adm --> Topic- The application owns three classes: the controller, the publisher and the topic configuration. Everything inside the box comes from auto-configuration and is shaped by
spring.kafka.*properties. - There is one
KafkaProducerfor the whole application. All request threads append to the same per-partition batches, and a single sender thread delivers them. KafkaAdmincreates theNewTopicbean at startup if the topic does not exist. Many organisations create topics through their platform tooling instead and setspring.kafka.admin.auto-create=false.- The two consumer groups each receive every event. They are outside this lesson, but they are the reason for the key and for publishing without Java type headers.
Message flow
Drawing diagram…
A sequence diagram. The HTTP client posts an order. The controller asks the publisher to publish, the publisher calls KafkaTemplate send and gets a CompletableFuture, and the controller waits on it for up to five seconds. The sender thread sends a Produce request with acks all, the leader acknowledges with partition and offset, the future completes and the controller answers 202. In the failure path the leader reports not enough replicas, the producer retries until the delivery timeout, the future completes exceptionally and the controller answers 503.
sequenceDiagram participant H as HTTP client participant C as OrderController participant P as OrderEventPublisher participant T as KafkaTemplate participant S as Producer sender thread participant L as Leader of orders.placed-2 H->>C: POST /orders with orderId o-42 C->>P: publish OrderPlaced P->>T: send topic, key o-42, event T-->>P: CompletableFuture of SendResult P-->>C: the same future Note over C: get with a 5 second timeout S->>L: Produce request, acks=all L-->>S: acknowledged, partition 2 offset 1287 S-->>C: future completes with SendResult C-->>H: 202 Accepted with partition and offset Note over S,L: failure path S->>L: Produce request L-->>S: NOT_ENOUGH_REPLICAS, retried until delivery.timeout.ms S-->>C: future completes exceptionally C-->>H: 503 Service Unavailable, retry with the same orderId
- The future is returned before anything is sent. The controller turns the asynchronous send into a synchronous answer by waiting on it with a timeout.
- On success the
RecordMetadatagives the partition and offset. Returning or logging them makes it possible to find the exact record later. - In the failure path the producer retries on its own until
delivery.timeout.ms. The application does not write a retry loop; it handles the final result. - The 503 tells the client the order was not confirmed. Because the client supplied the order id, retrying is safe for consumers that deduplicate on it.
In a real system
A typical online shop: the order service publishes OrderPlaced to orders.placed with 6 partitions, replication factor 3 and min.insync.replicas=2. The key is the order id. The payment service reads the topic in the group payment-service and the inventory service in the group inventory-service; each group gets every event and can use up to six consumers in parallel.
Traffic is a few hundred orders a second at peak. At that rate throughput tuning is not the concern; correctness and bounded latency are. linger.ms=10 adds at most 10 ms to a checkout that already takes far longer, and lz4 costs little. A clickstream topic in the same company would make the opposite choices, as the previous lesson shows.
Outbox pattern
Simulation, not a real clusterThe animated Build lesson shows the dual-write failure and the outbox that removes it.
Step 1 · The pattern
Save it, then tell everyone
An order comes in. The service saves it to its database, then publishes an event so shipping, email and analytics can react. Two writes, to two systems.
- order request
- done
Java and Spring Boot
The complete service: build file, event, configuration, publisher, controller and a test against an embedded broker. The code was written against the Spring for Apache Kafka 3.3 and Spring Boot 3.5 references and has not been compiled in this environment.
<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.5.16</version> <relativePath/> </parent> <groupId>com.example</groupId> <artifactId>order-service</artifactId> <version>0.0.1-SNAPSHOT</version> <properties> <java.version>21</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.kafka</groupId> <artifactId>spring-kafka</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework.kafka</groupId> <artifactId>spring-kafka-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build></project>Why it is written this way
- No versions on the Kafka dependencies. The Spring Boot parent manages
spring-kafka(3.3.x) and the matchingkafka-clients(3.9.x). Overriding one of them on its own is a common source of class-loading errors. - There is no Spring Boot starter for Kafka;
spring-kafkaon the classpath is what switches the auto-configuration on. spring-boot-starter-webbrings Jackson, whichJsonSerializeruses.spring-kafka-testprovides the embedded broker andKafkaTestUtilsused by the test.
package com.example.orders.events;import java.time.Instant;/** * Published to orders.placed when an order has been accepted. * The record key is orderId. */public record OrderPlaced( String eventId, String orderId, String customerId, long amountMinor, String currency, Instant occurredAt) {}Why it is written this way
- A record: events are immutable facts, and Jackson serialises records without extra annotations.
orderIdis the business identity and the Kafka key.eventIdidentifies this particular event, which is useful for tracing and for consumers that deduplicate per event.- Money is an integer amount in minor units plus a currency code, never a floating-point number.
occurredAtis the business time. The Kafka record also has a timestamp, but that is when the producer created the record, which differs when events are replayed or relayed.
spring: application: name: order-service kafka: bootstrap-servers: localhost:9092 producer: client-id: order-service key-serializer: org.apache.kafka.common.serialization.StringSerializer value-serializer: org.springframework.kafka.support.serializer.JsonSerializer acks: all compression-type: lz4 batch-size: 32768 properties: "[enable.idempotence]": true "[linger.ms]": 10 "[max.block.ms]": 5000 "[request.timeout.ms]": 10000 "[delivery.timeout.ms]": 30000 "[spring.json.add.type.headers]": falseapp: orders-topic: name: orders.placed partitions: 6 replicas: 3 min-insync-replicas: 2Why it is written this way
acks: allandenable.idempotence: trueare already the client defaults. They are written down so that a later edit which conflicts with idempotence fails at startup with aConfigExceptioninstead of silently switching idempotence off.linger.mshas no dedicated Spring Boot property, so it goes underproperties. It is set explicitly because the managed 3.9 client defaults to 0 while a 4.x client defaults to 5.max.block.ms: 5000bounds how longsendmay hold a request thread waiting for metadata or buffer space. The default is one minute.delivery.timeout.ms: 30000bounds how long the producer keeps retrying before the future fails. It must be at leastlinger.msplusrequest.timeout.ms(10 ms plus 10 s here). Shorter means faster failure answers and less tolerance for a slow leader election.spring.json.add.type.headers: falsestopsJsonSerializerfrom adding headers with the Java class name. Consumers then declare the type they expect (spring.json.value.default.type) and are not coupled to this service's package names.retriesis deliberately not set. The Kafka documentation recommends leaving it at its default and controlling retry behaviour withdelivery.timeout.ms.- Properties under
propertiesoverride the dedicated Spring Boot keys if both are given, so set each Kafka setting in one place only.
package com.example.orders;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplicationpublic class OrderServiceApplication { public static void main(String[] args) { SpringApplication.run(OrderServiceApplication.class, args); }}Why it is written this way
- Nothing Kafka-specific here.
@EnableKafkais only needed for@KafkaListenerin applications without Spring Boot; this service has no listeners and Boot configures the rest.
package com.example.orders.config;import org.springframework.boot.context.properties.ConfigurationProperties;@ConfigurationProperties("app.orders-topic")public record OrdersTopicProperties(String name, int partitions, int replicas, int minInsyncReplicas) {}Why it is written this way
- Topic settings are typed configuration, not string literals scattered through the code. The test overrides
replicasandmin-insync-replicasfor its single embedded broker.
package com.example.orders.config;import org.apache.kafka.clients.admin.NewTopic;import org.apache.kafka.common.config.TopicConfig;import org.springframework.boot.context.properties.EnableConfigurationProperties;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.kafka.config.TopicBuilder;@Configuration@EnableConfigurationProperties(OrdersTopicProperties.class)public class KafkaTopicConfig { @Bean NewTopic ordersPlacedTopic(OrdersTopicProperties props) { return TopicBuilder.name(props.name()) .partitions(props.partitions()) .replicas(props.replicas()) .config(TopicConfig.MIN_IN_SYNC_REPLICAS_CONFIG, String.valueOf(props.minInsyncReplicas())) .build(); }}Why it is written this way
- This is the only configuration class. There is no
ProducerFactoryorKafkaTemplatebean: Spring Boot's auto-configured ones are driven entirely byapplication.yml. Define your own only when you need something properties cannot express, such as a second template with different serializers. - The topic's durability settings sit next to the producer that depends on them.
acks=allmeans little without replication factor 3 andmin.insync.replicas=2. - The auto-configured
KafkaAdmincreates the topic at startup if it is missing and leaves an existing topic's configuration alone by default. If your platform team owns topics, delete this bean and setspring.kafka.admin.auto-create=false. - Six partitions is a starting point for a few hundred records a second. Increasing the count later changes which partition a key maps to, so ordering per order id is not preserved across the change.
package com.example.orders.messaging;import java.util.concurrent.CompletableFuture;import org.apache.kafka.clients.producer.RecordMetadata;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.kafka.core.KafkaTemplate;import org.springframework.kafka.support.SendResult;import org.springframework.stereotype.Component;import com.example.orders.config.OrdersTopicProperties;import com.example.orders.events.OrderPlaced;@Componentpublic class OrderEventPublisher { private static final Logger log = LoggerFactory.getLogger(OrderEventPublisher.class); private final KafkaTemplate<String, OrderPlaced> kafkaTemplate; private final String topic; public OrderEventPublisher(KafkaTemplate<String, OrderPlaced> kafkaTemplate, OrdersTopicProperties topicProperties) { this.kafkaTemplate = kafkaTemplate; this.topic = topicProperties.name(); } /** * Publishes the event keyed by order id. The returned future completes when the broker * has acknowledged the record, or exceptionally when the producer has given up. */ public CompletableFuture<SendResult<String, OrderPlaced>> publish(OrderPlaced event) { CompletableFuture<SendResult<String, OrderPlaced>> future; try { future = kafkaTemplate.send(topic, event.orderId(), event); } catch (RuntimeException ex) { // Thrown on the calling thread, before the record was buffered (for example serialisation). log.error("OrderPlaced {} for order {} could not be handed to the producer", event.eventId(), event.orderId(), ex); return CompletableFuture.failedFuture(ex); } // Runs on the producer's I/O thread: keep it short and never block here. return future.whenComplete((result, ex) -> { if (ex != null) { log.error("OrderPlaced {} for order {} was not delivered to {}", event.eventId(), event.orderId(), topic, ex); return; } RecordMetadata metadata = result.getRecordMetadata(); log.info("OrderPlaced {} for order {} stored at {}-{} offset {}", event.eventId(), event.orderId(), metadata.topic(), metadata.partition(), metadata.offset()); }); }}Why it is written this way
send(topic, key, value)withorderIdas the key. The three-argument form is used on purpose: the two-argumentsend(topic, value)sends a record without a key.- The auto-configured template can be injected as
KafkaTemplate<String, OrderPlaced>; the generic types must match the serializers configured inapplication.yml. - Both failure paths end in a failed future, so callers have one thing to handle. An exception thrown by
senditself (the record never reached the buffer) is converted withCompletableFuture.failedFuture. - The publisher returns the future instead of deciding what failure means. Whether to wait, fail a request, or drop the event is the caller's decision and differs per use case.
- The
whenCompletecallback only logs. It runs on the producer's sender thread, where slow work would delay every other record this application sends. - The publisher does not retry. The producer already retries transient errors until
delivery.timeout.ms; an application-level resend on top of that creates a new record that idempotence does not deduplicate. - Logging partition and offset on success gives you an exact address for the record when someone later asks whether an order event was sent.
package com.example.orders.api;import java.time.Instant;import java.util.UUID;import java.util.concurrent.ExecutionException;import java.util.concurrent.TimeUnit;import java.util.concurrent.TimeoutException;import org.apache.kafka.clients.producer.RecordMetadata;import org.springframework.http.HttpStatus;import org.springframework.http.ResponseEntity;import org.springframework.kafka.support.SendResult;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RestController;import com.example.orders.events.OrderPlaced;import com.example.orders.messaging.OrderEventPublisher;@RestController@RequestMapping("/orders")public class OrderController { private static final long PUBLISH_TIMEOUT_SECONDS = 5; private final OrderEventPublisher publisher; public OrderController(OrderEventPublisher publisher) { this.publisher = publisher; } public record PlaceOrderRequest(String orderId, String customerId, long amountMinor, String currency) { } public record PlaceOrderResponse(String orderId, String status, Integer partition, Long offset) { } @PostMapping public ResponseEntity<PlaceOrderResponse> placeOrder(@RequestBody PlaceOrderRequest request) { if (request.orderId() == null || request.orderId().isBlank()) { return ResponseEntity.badRequest().build(); } OrderPlaced event = new OrderPlaced( UUID.randomUUID().toString(), request.orderId(), request.customerId(), request.amountMinor(), request.currency(), Instant.now()); try { SendResult<String, OrderPlaced> result = publisher.publish(event).get(PUBLISH_TIMEOUT_SECONDS, TimeUnit.SECONDS); RecordMetadata metadata = result.getRecordMetadata(); return ResponseEntity.accepted() .body(new PlaceOrderResponse(request.orderId(), "ACCEPTED", metadata.partition(), metadata.offset())); } catch (ExecutionException ex) { // The producer gave up or the broker rejected the record. Already logged by the publisher. return unavailable(request.orderId(), "NOT_PUBLISHED"); } catch (TimeoutException ex) { // Our wait ended first. The producer may still deliver the record. return unavailable(request.orderId(), "NOT_CONFIRMED"); } catch (InterruptedException ex) { Thread.currentThread().interrupt(); return unavailable(request.orderId(), "NOT_CONFIRMED"); } } private static ResponseEntity<PlaceOrderResponse> unavailable(String orderId, String status) { return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE) .body(new PlaceOrderResponse(orderId, status, null, null)); }}Why it is written this way
- The client supplies
orderId. It is the key, and it is what makes a retried request harmless: the second event carries the same order id, and consumers that deduplicate on it process the order once. - The controller waits for the acknowledgement because an accepted order with no event is a silent failure. For events nobody depends on you would return immediately and let the publisher's log line and metrics cover failures.
getalways has a timeout. The Spring reference recommends this for blocking sends; without one a request thread waits for as long as the producer keeps trying.- The two failure answers are different on purpose.
NOT_PUBLISHEDmeans the producer reported a failure.NOT_CONFIRMEDmeans the outcome is unknown and the record may still arrive, which is another reason consumers must tolerate duplicates. - With
linger.ms=10each request waits up to 10 ms for its batch to be sent. The Spring reference mentions callingflush()before waiting; that would send immediately but gives up batching and can delay other threads sharing the producer, so this service accepts the 10 ms instead. InterruptedExceptionrestores the interrupt flag before answering, so the server can shut the thread down properly.- Input validation is reduced to one check to keep the example short; a real service would validate the whole request.
package com.example.orders.messaging;import static org.assertj.core.api.Assertions.assertThat;import java.time.Instant;import java.util.List;import java.util.Map;import java.util.concurrent.TimeUnit;import org.apache.kafka.clients.consumer.Consumer;import org.apache.kafka.clients.consumer.ConsumerConfig;import org.apache.kafka.clients.consumer.ConsumerRecord;import org.apache.kafka.common.serialization.StringDeserializer;import org.junit.jupiter.api.Test;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.test.context.SpringBootTest;import org.springframework.kafka.core.DefaultKafkaConsumerFactory;import org.springframework.kafka.support.SendResult;import org.springframework.kafka.test.EmbeddedKafkaBroker;import org.springframework.kafka.test.context.EmbeddedKafka;import org.springframework.kafka.test.utils.KafkaTestUtils;import org.springframework.test.annotation.DirtiesContext;import com.example.orders.events.OrderPlaced;@SpringBootTest(properties = { "app.orders-topic.replicas=1", "app.orders-topic.min-insync-replicas=1"})@EmbeddedKafka(kraft = true, partitions = 1)@DirtiesContextclass OrderEventPublisherTest { private static final String TOPIC = "orders.placed"; @Autowired private OrderEventPublisher publisher; @Autowired private EmbeddedKafkaBroker embeddedKafka; @Test void publishesTheEventAsJsonKeyedByOrderId() throws Exception { OrderPlaced event = new OrderPlaced( "evt-1", "order-42", "customer-7", 4999, "EUR", Instant.parse("2026-01-15T10:00:00Z")); SendResult<String, OrderPlaced> result = publisher.publish(event).get(10, TimeUnit.SECONDS); assertThat(result.getRecordMetadata().topic()).isEqualTo(TOPIC); assertThat(result.getRecordMetadata().hasOffset()).isTrue(); Map<String, Object> consumerProps = KafkaTestUtils.consumerProps("order-publisher-test", "true", embeddedKafka); consumerProps.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); consumerProps.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class); consumerProps.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class); try (Consumer<String, String> consumer = new DefaultKafkaConsumerFactory<String, String>(consumerProps).createConsumer()) { consumer.subscribe(List.of(TOPIC)); ConsumerRecord<String, String> received = KafkaTestUtils.getSingleRecord(consumer, TOPIC); assertThat(received.key()).isEqualTo("order-42"); assertThat(received.partition()).isEqualTo(result.getRecordMetadata().partition()); assertThat(received.offset()).isEqualTo(result.getRecordMetadata().offset()); assertThat(received.value()).contains("\"orderId\":\"order-42\""); } }}Why it is written this way
@EmbeddedKafka(kraft = true)starts an in-process broker in KRaft mode. In Spring for Apache Kafka 3.3 the attribute still defaults to a ZooKeeper-based test broker, so it is set explicitly.- Since Spring for Apache Kafka 3.0.10 the embedded broker's address is published as
spring.kafka.bootstrap-serversby default, so the application's own auto-configured producer and admin connect to it with no extra wiring. - The test overrides the topic to replication factor 1 and
min.insync.replicas=1. With one broker, the production values would make everyacks=allsend fail with too few in-sync replicas. - The topic is created by the application's own
NewTopicbean, so the test also proves that the topic configuration is valid. - The assertion reads the record back with a plain string consumer. It checks what other services will actually see on the wire: the key, and JSON that does not need this service's classes to read.
@DirtiesContextfollows the Spring reference's advice for embedded broker tests, so the context is closed before the broker shuts down.- An embedded broker checks wiring and serialisation. Behaviour that depends on a real cluster (replication, leader failover) needs Testcontainers or a test environment; see testing and observability.
Configuration
Spring Boot keys are from the Spring Boot 3.5 application properties reference; where Boot documents no default, the Kafka client's default applies. Kafka client defaults are the documented ones and are the same in the 3.9 and 4.x clients unless stated.
spring.kafka.bootstrap-serversDefault none documented (Spring Boot falls back to localhost:9092)
- What it does
- Host and port pairs for the initial connection. Applies to producer, consumer and admin unless overridden per client type.
- When to change it
- List more than one broker so startup does not depend on a single one being up.
spring.kafka.producer.acksDefault none in Spring Boot; Kafka client default all
- What it does
- How many acknowledgements the leader needs before a request is complete:
0,1orall(the in-sync replicas at that moment). - When to change it
- Keep
allfor business events. It is only a durability guarantee together with replication factor 3 andmin.insync.replicas=2on the topic.
spring.kafka.producer.properties.enable.idempotenceDefault true (Kafka client)
- What it does
- The broker discards duplicates caused by the producer's own retries and keeps batches in order, per partition, within a producer session. Requires
acks=all, retries above 0 and at most 5 in-flight requests. - When to change it
- Leave it on. Setting it explicitly turns a conflicting setting into a startup error instead of silently disabling it.
spring.kafka.producer.properties.linger.msDefault 0 in kafka-clients 3.9 (Spring Boot 3.5); 5 in kafka-clients 4.x
- What it does
- How long a batch may wait for more records before it is sent.
- When to change it
- Set it explicitly. A few milliseconds where a caller waits for the acknowledgement; tens of milliseconds for high-volume streams nobody waits on.
spring.kafka.producer.batch-sizeDefault none in Spring Boot; Kafka client default 16384
- What it does
- Upper bound in bytes for one partition's batch.
- When to change it
- Raise it only when batches already fill; see the previous lesson for how to tell.
spring.kafka.producer.compression-typeDefault none in Spring Boot; Kafka client default none
- What it does
- Codec applied to each batch by the producer:
none,gzip,snappy,lz4orzstd. - When to change it
- Enable
lz4orzstdfor JSON at any real volume. It changes cost, not guarantees.
spring.kafka.producer.properties.delivery.timeout.msDefault 120000 (2 minutes)
- What it does
- Upper bound from
sendreturning until success or failure is reported, including time in the buffer and all retries. - When to change it
- Lower it when a caller is waiting, but leave room for a leader election. Must be at least
linger.msplusrequest.timeout.ms.
spring.kafka.producer.properties.max.block.msDefault 60000 (1 minute)
- What it does
- How long
senditself may block waiting for metadata or buffer space. - When to change it
- Lower it whenever
sendis called from a request thread.
spring.kafka.producer.retriesDefault none in Spring Boot; Kafka client default 2147483647
- What it does
- Number of retries for transient errors. Retries stop at
delivery.timeout.mswhatever the count. - When to change it
- Leave it unset and control retrying with
delivery.timeout.ms, as the Kafka documentation advises. Setting 0 conflicts with idempotence.
spring.kafka.producer.properties.spring.json.add.type.headersDefault true
- What it does
- Whether
JsonSerializeradds record headers naming the Java type of the value. - When to change it
- Set
falsewhen consumers are other services, or map logical names withspring.json.type.mapping, so consumers do not depend on your class names.
spring.kafka.admin.auto-createDefault true
- What it does
- Whether
NewTopicbeans are created on the cluster when the application context starts. - When to change it
- Set
falsewhere topics are created by platform tooling and applications lack the permission to create them.
spring.kafka.template.observation-enabledDefault false
- What it does
- Whether
KafkaTemplaterecords Micrometer observations (timers and tracing spans) for sends. - When to change it
- Enable it when you run Micrometer tracing so a send appears in the trace of the request that caused it.
Hands-on exercise
Change the service's settings and classify the effect
Start from this service's configuration in the simulator, change one setting at a time and decide for each change whether it moved throughput and latency, or the delivery guarantee.
Steps · 0 of 8 done
Producer configuration simulator: the order service
Simulation · not a real clusterThe preset matches this lesson's application.yml. Change one control at a time and read all three result panels after each change. The simulation is deterministic and conceptual, not a benchmark.
What you should see
acks, idempotence, retries and in-flight requests change what can be lost, duplicated or reordered, and barely change throughput. linger.ms, batch.size and compression change requests, bytes and latency, and leave the guarantee alone. The two configurations you write should therefore share every reliability line and differ only in linger.ms, batch.size, compression and the time bounds.
What can go wrong
Ignoring the future returned by send
- Symptom
- Orders are accepted over HTTP but some never reach downstream services. The only trace is an ERROR line from
LoggingProducerListenerminutes later. - Cause
sendreturns before the record leaves the process. The code answered the caller without looking at the outcome, so a failed delivery had nowhere to go.- Fix
- Decide per event type: wait on the future with a timeout and fail the request, or attach a callback that records the failure somewhere it will be acted on. For events tied to a database change, use an outbox.
Treating a timeout as “not sent”
- Symptom
- After a slow period, some orders have two
OrderPlacedevents with different event ids. - Cause
future.gettimed out, the caller retried and the application sent a second record, while the producer went on to deliver the first. Producer idempotence does not cover a second call tosend.- Fix
- Give events a stable business identity (the client-supplied order id here) and make consumers deduplicate on it. Keep the wait in
getanddelivery.timeout.msclose to each other so the unknown window is short.
Slow work in the send callback
- Symptom
- Produce latency climbs for the whole application and
record-queue-time-avggrows, although the brokers are healthy. - Cause
- A
whenCompletecallback orProducerListenerwrites to a database or calls another service. It runs on the producer's single I/O thread and holds up every batch. - Fix
- Keep callbacks to logging and counters, or hand off with
whenCompleteAsyncand your own executor.
Creating a producer for every request
- Symptom
- Rising connection counts and memory on brokers, slow sends, no batching, although message volume is ordinary.
- Cause
- Code builds a new
KafkaProducer,DefaultKafkaProducerFactoryorKafkaTemplateover a new factory per request or per tenant. Each one opens connections, fetches metadata and registers its own idempotent producer state on the brokers. - Fix
- Inject the single auto-configured
KafkaTemplate. The Break card A producer for every request shows where this ends.
Saving to the database and sending in the same method
- Symptom
- Occasionally an order exists in the database with no event, or an event exists for an order that was rolled back.
- Cause
- Two independent writes.
@Transactionalon the method covers the database only; the Kafka send is not part of that transaction, and a Kafka transaction would not include the database either. - Fix
- Write the event to an outbox table in the same database transaction and publish from there. See transactional outbox.
Type headers tying consumers to the producer's classes
- Symptom
- A consumer in another service fails to deserialise with an error about a class not being in the trusted packages, or a class that does not exist there.
- Cause
JsonSerializeradds type headers by default, namingcom.example.orders.events.OrderPlaced. The consumingJsonDeserializertries to use that class name.- Fix
- Publish without type headers and let each consumer set
spring.json.value.default.type, or agree on logical names withspring.json.type.mappingon both sides.
How to troubleshoot
The first request hangs for max.block.ms and then fails with a TimeoutException saying the topic is not present in metadata
Check
bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders.placed
- How to read it
- If the command cannot connect,
bootstrap-serversor the network is wrong. If the topic is missing, it was never created: checkspring.kafka.admin.auto-createand whether the application is allowed to create topics.
Sends fail with NotEnoughReplicasException after delivery.timeout.ms
Check
bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders.placed (compare the Isr column with min.insync.replicas)
- How to read it
- Fewer replicas are in sync than
min.insync.replicas, so the leader refusesacks=allwrites. That is the guarantee working. Fix the brokers; do not loweracks. On a single-broker development cluster, the topic's replication factor andmin.insync.replicasmust both be 1.
The application fails at startup with a ConfigException about idempotence
Check
The producer section of application.yml: `acks`, `retries` and `max.in.flight.requests.per.connection`
- How to read it
- Idempotence was enabled explicitly and another setting conflicts with it:
acksother thanall,retriesof 0, or more than 5 in-flight requests. Remove the conflicting setting.
Not sure which settings the producer is actually running with
Check
The `ProducerConfig values:` block that the Kafka client logs at INFO when the first producer is created
- How to read it
- It lists every effective setting after Spring Boot properties,
properties.*overrides and client defaults are merged. Checklinger.ms,acksandenable.idempotencethere instead of assuming.
Need to see whether sends are failing or being retried in a running service
Check
Producer metrics `record-error-rate`, `record-retry-rate` and `request-latency-avg` (Spring Boot exposes Kafka client metrics through Micrometer when Actuator is present)
- How to read it
- A retry rate above zero with no errors means the producer is absorbing transient problems. A rising error rate means sends are reaching
delivery.timeout.msor being rejected; look at the exception in the publisher's log.
Key takeaways
- Spring Boot builds the
ProducerFactory, one shared producer and theKafkaTemplatefromspring.kafka.*; your code supplies the key, the event and the decision about failure. sendreturns a future before anything is sent. Someone must look at the outcome, with a timeout if they wait.- A timeout means unknown, not failed. Give events a stable business id so that a repeated request is harmless for consumers that deduplicate.
- Producer idempotence covers the producer's own retries only. It does not cover your application calling
sendtwice. - Defaults come from the client library version in the application: Spring Boot 3.5 runs a 3.9 client where
linger.msis 0. Write down the settings you rely on. acks, idempotence and retries set the guarantee;linger.ms,batch.sizeand compression set cost and latency. Tune the second group freely and the first group deliberately.- When an event must match a database write, a direct send is a dual write. Use a transactional outbox.
Practical check
Small scenarios, one decision each. Pick what you would do, then read why.
Scenario 1 of 3
Your order service waits on the send future for 5 seconds with delivery.timeout.ms=30000. During a leader election, 40 requests get a timeout from get() and return 503. The mobile app retries each one. Next morning the payment team reports 31 orders with two OrderPlaced events.
What is the most appropriate correction?
Scenario 2 of 3
A colleague proposes this producer section to speed up checkout: acks: 1, enable.idempotence: true, linger.ms: 0, compression-type: none. Load is about 300 orders a second on 6 partitions, the topic has replication factor 3 and min.insync.replicas=2, and p99 produce latency today is 12 ms.
What should you tell them?
Scenario 3 of 3
An order service method annotated @Transactional saves the order with JPA and then calls kafkaTemplate.send(...).get(5, SECONDS). In a load test with brokers restarted at random, 0.2% of orders are in the database with no event, and a handful of events refer to orders that are not in the database.
Which change addresses both symptoms?
References
References: Spring for Apache Kafka 3.3 reference: Sending Messages (KafkaTemplate, ProducerListener, DefaultKafkaProducerFactory) ↗ · Spring for Apache Kafka 3.3 reference: Serialization, Deserialization, and Message Conversion (JsonSerializer, type headers) ↗ · Spring for Apache Kafka 3.3 reference: Testing Applications (@EmbeddedKafka, KafkaTestUtils) ↗ · Spring Boot 3.5 reference: Apache Kafka Support (auto-configuration, additional properties, embedded Kafka) ↗ · Spring Boot 3.5: Common application properties (spring.kafka.producer.*) ↗ · Spring Boot 3.5: Managed dependency coordinates (spring-kafka 3.3.x, kafka-clients 3.9.x) ↗ · Apache Kafka 4.4: Producer configs (acks, enable.idempotence, linger.ms, delivery.timeout.ms, max.block.ms) ↗ · Apache Kafka 3.9: Producer configs (defaults of the client Spring Boot 3.5 manages) ↗ · Apache Kafka 4.4: KafkaProducer Javadoc (callbacks run on the I/O thread) ↗ · Report a problem