This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.
Status
Current state: "Draft"
Discussion thread: here [Change the link from the KIP proposal email archive to your own email thread]
JIRA: here [Change the link from KAFKA-1 to your own ticket]
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
Motivation
This KIP introduces a way to list the client metrics configuration resources introduced by KIP-714. The client metrics configuration resources can be created, read, updated and deleted using the existing RPCs and the kafka-configs.sh
tool, in common with all of the other configuration resources.
Proposed Changes
The KIP adds a new RPC to the Kafka protocol called ListClientMetrics
which responds with a list of the client metrics configuration resources. It also adds AdminClient.listClientMetrics
to provide a programming interface for building tools to list client metrics configuration resources.
Public Interfaces
This KIP introduces support for obtaining a list of client metrics configuration resources to the Kafka protocol and admin client.
Kafka Protocol
ListClientMetrics RPC
{ "apiKey": XX, "type": "request", "listeners": ["broker", "zkBroker", "controller"], "name": "ListClientMetricsRequest", "validVersions": "0", "flexibleVersions": "0+", "fields": [ ]} } { "apiKey": XX, "type": "response", "name": "ListClientMetricsResponse", "validVersions": "0", "flexibleVersions": "0+", "fields": [ { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+", "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+" }, { "name": "ClientMetrics", "type": "[]ClientMetricsList", "versions": "0+", "fields": [ { "name": "Name", "type": "string", "versions": "0+" } ]} ] }
Admin Client
The following methods are added to the org.apache.kafka.client.admin.Admin
interface.
/** * List the client metrics configuration resources available in the cluster. * * @param options The options to use when listing the client metrics resources. * @return The ListClientMetricsResult. */ ListClientMetricsResult listClientMetrics(ListClientMetricsOptions options); /** * List the client metrics configuration resources available in the cluster with the default options. * <p> * This is a convenience method for {@link #listClientMetrics(ListClientMetricsOptions)} with default options. * See the overload for more details. * * @return The ListClientMetricsResult. */ default ListClientMetricsResult listClientMetrics() { return listClientMetrics(new ListClientMetricsOptions()); }
The options are defined as follows:
package org.apache.kafka.client.admin; /** * Options for {@link Admin#listClientMetrics()}. * * The API of this class is evolving, see {@link Admin} for details. */ @InterfaceStability.Evolving public class ListClientMetricsOptions extends AbstractOptions<ListClientMetricsOptions> { }
The result is defined as follows:
package org.apache.kafka.clients.admin; /** * The result of the {@link Admin#listClientMetrics()} call. * <p> * The API of this class is evolving, see {@link Admin} for details. */ @InterfaceStability.Evolving public class ListClientMetricsResult { /** * Returns a future that yields either an exception, or the full set of client metrics * listings. * * In the event of a failure, the future yields nothing but the first exception which * occurred. */ public KafkaFuture<Collection<ClientMetricsListing>> all() { } }
And finally the listing itself, which is initially only the name:
package org.apache.kafka.clients.admin; @InterfaceStability.Evolving public class ClientMetricsListing { private final String id; public ClientMetricsListing( String name ) { this.name = name; } public String name() { return name; } }
Security
Client metrics subscriptions are secured using the CLUSTER resource.
API Request | Resource | ACL operation |
---|---|---|
ListClientMetrics | CLUSTER | DESCRIBE_CONFIGS |
Compatibility, Deprecation, and Migration Plan
No impact.
Test Plan
The KIP implementation will be accompanied by the usual set of unit tests.
Rejected Alternatives
None.