This is an automated email from the ASF dual-hosted git repository.
AndrewJSchofield pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 6784c621e16 KAFKA-20809: Updated getting started docs with share group
DLQ. (#22950)
6784c621e16 is described below
commit 6784c621e16117734d04436f6788cc050c0033f3
Author: Sushant Mahajan <[email protected]>
AuthorDate: Mon Jul 27 17:21:18 2026 +0530
KAFKA-20809: Updated getting started docs with share group DLQ. (#22950)
* Add overview of share group DLQ in `upgrade.md`.
* Update `basic-kafka-operations.md` with a new section on configuring
share groups with DLQ.
Reviewers: Andrew Schofield <[email protected]>
---
docs/getting-started/upgrade.md | 1 +
docs/operations/basic-kafka-operations.md | 44 +++++++++++++++++++++++++++++++
2 files changed, 45 insertions(+)
diff --git a/docs/getting-started/upgrade.md b/docs/getting-started/upgrade.md
index 4e8a7700190..c504d0c1630 100644
--- a/docs/getting-started/upgrade.md
+++ b/docs/getting-started/upgrade.md
@@ -48,6 +48,7 @@ type: docs
* The `kafka-cluster.sh` tool now provides an `api-versions` command to
display the API versions supported by the brokers or controllers, and it
accepts both `--bootstrap-server` and `--bootstrap-controller`. As a result,
`kafka-broker-api-versions.sh` is deprecated and will be removed in the next
major release; use `kafka-cluster.sh api-versions` instead. For further
details, please refer to
[KIP-1220](https://cwiki.apache.org/confluence/x/-QkbFw).
* Brokers can now record a human-readable description of each streams
group's processing topology via a pluggable backend, retrievable through
`Admin#describeStreamsGroups` and `kafka-streams-groups.sh --describe
--topology`. The feature is disabled unless the new broker configuration
`group.streams.topology.description.plugin.class` is set to a
`StreamsGroupTopologyDescriptionPlugin` implementation; on the client side, the
new Kafka Streams configuration `topology.description.push.ena [...]
* The `kafka-producer-perf-test.sh` tool now supports `--record-key-range`,
`--key-distribution`, and `--random-seed` options to control the distribution
of record keys. Use `--key-distribution range` for sequential key assignment
(round-robin over the key range) or `--key-distribution random` for random key
selection. The `--random-seed` option allows reproducible benchmark runs when
using random key distribution. For further details, please refer to
[KIP-1299](https://cwiki.apache.or [...]
+ * Share groups now support dead-letter queue functionality as outlined in
[KIP-1191](https://cwiki.apache.org/confluence/x/fApJFg). Any records which are
released (beyond max delivery count) or rejected by the share consumer become
eligible for DLQ. Share group DLQ gets enabled when the Kafka feature
`share.version` is upgraded to 2. The user can configure a DLQ topic on a share
group by setting the dynamic config `errors.deadletterqueue.topic.name`
(default `""`) to the name of the DL [...]
## Upgrading to 4.3.0
diff --git a/docs/operations/basic-kafka-operations.md
b/docs/operations/basic-kafka-operations.md
index d5146f7404d..8710c283a20 100644
--- a/docs/operations/basic-kafka-operations.md
+++ b/docs/operations/basic-kafka-operations.md
@@ -350,6 +350,50 @@ $ bin/kafka-share-groups.sh --bootstrap-server
localhost:9092 --delete --group m
Deletion of requested share groups ('my-share-group') was successful.
```
+## Configuring dead-letter queues (DLQ) on share groups
+
+Share group dead-letter queues are enabled if the `share.version` feature at
least 2:
+
+```bash
+$ bin/kafka-features.sh --bootstrap-server localhost:9092 describe | grep
share.version
+Feature: share.version SupportedMinVersion: 0
SupportedMaxVersion: 2 FinalizedVersionLevel: 2
Epoch: 106
+```
+
+Set DLQ topic on share group:
+
+```bash
+$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config
"errors.deadletterqueue.topic.name=dlq.gs1dlqtopic" --entity-type groups
--entity-name my-share-group
+Completed updating config for group my-share-group.
+```
+
+To enable share group DLQ topic auto creation (default disabled):
+
+```bash
+$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config
"errors.deadletterqueue.auto.create.topics.enable=true" --entity-type brokers
--entity-default
+Completed updating default config for brokers in the cluster.
+```
+
+To set your own Kafka topic as share group DLQ topic, you must set certain
dynamic configs on the DLQ topic post creation. If cluster dynamic config to
auto create share group DLQ topic is enabled
(`errors.deadletterqueue.auto.create.topics.enable=true`), the configs are
attached automatically to the auto created topics.
+
+```bash
+$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config
"errors.deadletterqueue.group.enable=true" --entity-type topics --entity-name
dlq.gs1dlqtopic
+Completed updating config for topic dlq.gs1dlqtopic.
+```
+
+To change the default `dlq.` share group DLQ topic prefix, set the dynamic
cluster config `errors.deadletterqueue.topic.name.prefix` to desired value. The
default value is `dlq.`.
+
+```bash
+$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config
"errors.deadletterqueue.topic.name.prefix=com.mycompany.dlq." --entity-type
brokers --entity-default
+Completed updating default config for brokers in the cluster.
+```
+
+By default, the records written to the DLQ topic just include metadata about
the source records such as the topic, partition and offset. You can set the
`errors.deadletterqueue.copy.read.enable` configuration for the share group so
the source record key and value are copied to the DLQ topic.
+
+```bash
+$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config
"errors.deadletterqueue.copy.record.enable=true" --entity-type groups
--entity-name my-share-group
+Completed updating config for group my-share-group.
+```
+
## Expanding your cluster
Adding servers to a Kafka cluster is easy, just assign them a unique broker id
and start up Kafka on your new servers. However these new servers will not
automatically be assigned any data partitions, so unless partitions are moved
to them they won't be doing any work until new topics are created. So usually
when you add machines to your cluster you will want to migrate some existing
data to these machines.
