THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
Public Interfaces
ListGroups API
Update Bump ListGroupsRequest version to 4 and include a new flexible field "states".
| Code Block |
|---|
{
"apiKey": 16,
"type": "request",
"name": "ListGroupsRequest",
// Version 1 and 2 are the same as version 0.
//
// Version 3 is the first flexible version.
//
// KIP-518Version 4 adds the States flexible field (KIP-518).
"validVersions": "0-34",
"flexibleVersions": "3+",
"fields": [
{ "name": "States", "type": "[]string", "versions": "3+", "tag": 0, "taggedVersions": "3+",
"about": "The states of the groups we want to list", "fields": [
{ "name": "Name", "type": "string", "versions": "3+", "about": "The group state" }
]}
]
} |
Update Bump ListGroupsResponse version to 4 and include a new flexible field "group_state".
| Code Block |
|---|
{
"apiKey": 16,
"type": "response",
"name": "ListGroupsResponse",
// Version 1 adds the throttle time.
//
// Starting in version 2, on quota violation, brokers send out responses before throttling.
//
// Version 3 is the first flexible version.
//
// Version KIP-5184 adds the GroupState flexible field (KIP-518).
"validVersions": "0-34",
"flexibleVersions": "3+",
"fields": [
{ "name": "ThrottleTimeMs", "type": "int32", "versions": "1+", "ignorable": true,
"about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
{ "name": "ErrorCode", "type": "int16", "versions": "0+",
"about": "The error code, or 0 if there was no error." },
{ "name": "Groups", "type": "[]ListedGroup", "versions": "0+",
"about": "Each group in the response.", "fields": [
{ "name": "GroupId", "type": "string", "versions": "0+", "entityType": "groupId",
"about": "The group ID." },
{ "name": "ProtocolType", "type": "string", "versions": "0+",
"about": "The group protocol type." },
{ "name": "GroupState", "type": "string", "versions": "34+", "tag": 0, "taggedVersions": "34+", "ignorable": true,
"about": "The group state string." }
]}
]
} |
This KIP bumps the version of this request to avoid any version incompatibility issues with older broker. See rejected alternatives.
If States is not specified or if it's empty in the request, from version 34, all groups will be returned without their states, like in versions < 4. At the moment, consumer group state is already serialized as a STRING in DescribeGroupsResponse, so serializing it the same way here.
When attempting to list groups with states using an older broker, an UnsupportedVersionException will be raised in the client.
AdminClient API
To expose this feature in the AdminClient API, ListConsumerGroupsOptions will be updated.
| Code Block | ||||
|---|---|---|---|---|
| ||||
public class ListConsumerGroupsOptions extends AbstractOptions<ListConsumerGroupsOptions> {
/**
* Only groups in these states will be returned by listConsumerGroups()
* ByIf not defaultset, all groups are returned without their states
*/
public voidListConsumerGroupsOptions inStates(Set<ConsumerGroupState> states) {}
/**
* All groups will be returned by listConsumerGroups()
*/
public ListConsumerGroupsOptions inAnyState() {}
/**
* Returns the list of States that are requested
*/
public Set<ConsumerGroupState> states() {}
} |
...
To expose this feature in the command line tools, ConsumerGroupCommand tool will be updated to support filtering by group states. A new argument existing flag "--statesstate" will be updated to allow to specify specifying a list of group states . This new option will only be valid when used with "–list". When specified, the state of each group will be printed next to the group id.
For example:
| No Format |
|---|
./kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list group1 group2 ./kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list --states group1state GROUP STATE group1 stable group2 empty ./kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list --states stable GROUP STATE group1 stable |
Compatibility, Deprecation, and Migration Plan
...
- Allow specifying a filter in ListGroups to retrieve groups by name or by state using wildcard
- Unclear if it's a common use case
- Keep ListGroups v3
- Keeping v3 would allow cases where brokers could support v3 but not the new optional field. In that case, if a client specifies States in its request, brokers would still return the full list of groups without states. This looked confusing. In case broker don't support a feature, a UnsupportedVersionException is preferred.