You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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.

  • No labels