Status

Current state: Under Discussion

Discussion thread: here

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

The DescribeLogDirs API is used to get information about the log directories of Kafka brokers. If an Authorizer is used, the user needs to have Describe on the Cluster resource. At the moment, if the user does not have this necessary authorization, an empty response is returned, and clients interpret an empty response as a CLUSTER_AUTHORIZATION_FAILED error [0].

To make this API consistent with all others, and to effectively identify potential UNKNOWN_SERVER_ERRORs, this KIP proposes adding a top-level error code field.

Public Interfaces

DescribeLogDirs API

Bump DescribeLogDirsRequest and DescribeLogDirsResponse to v3 and add a new field ErrorCode to DescribeLogDirsResponse.

{
  "apiKey": 35,
  "type": "response",
  "name": "DescribeLogDirsResponse",
  // Starting in version 1, on quota violation, brokers send out responses before throttling.
  "validVersions": "0-3",
  // Version 2 is the first flexible version.
  // Version 3 adds the top-level ErrorCode field
  "flexibleVersions": "2+",
  "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": "3+", "about": "The error code, or 0 if there was no error." },
    { "name": "Results", "type": "[]DescribeLogDirsResult", "versions": "0+",
      "about": "The log directories.", "fields": [
      ...
      ]}
    ]}
  ]
}

Proposed Changes

The necessary components, KafkaApis, DescribeLogDirsRequest and KafkaAdminClient, will be updated to use this new field if available.

Compatibility, Deprecation, and Migration Plan

N/A, only new clients will use the new version, this does not change the behaviour of existing clients.

Rejected Alternatives

If there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way.