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: DraftAccepted

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

Describe the problems you are trying to solve.

Public Interfaces

Briefly list any new interfaces that will be introduced as part of this proposal or any existing interfaces that will be removed or changed. The purpose of this section is to concisely call out the public contract that will come along with this feature.

A public interface is any change to the following:

• Binary log format

• The network protocol and api behavior

• Any class in the public packages under clientsConfiguration, especially client configuration

  • org/apache/kafka/common/serialization

  • org/apache/kafka/common

  • org/apache/kafka/common/errors

  • org/apache/kafka/clients/producer

  • org/apache/kafka/clients/consumer (eventually, once stable)

• Monitoring

• Command line tools and arguments

• Anything else that will likely break existing users in some way when they upgrade

Proposed Changes

Describe the new thing you want to do in appropriate detail. This may be fairly extensive and have large subsections of its own. Or it may be a few sentences. Use judgement based on the scope of the change.

Compatibility, Deprecation, and Migration Plan

• What impact (if any) will there be on existing users?
• If we are changing behavior how will we phase out the older behavior?
• If we need special migration tools, describe them here.
• When will we remove the existing behavior?

Test Plan

Describe in few sentences how the KIP will be tested. We are mostly interested in system tests (since unit-tests are specific to implementation details). How will we know that the implementation works as expected? How will we know nothing broke?

Rejected Alternatives

When using the Kafka command-line tools to do simple performance tests, it quickly becomes evident that kafka-producer-perf-test.sh  and the equivalent consumer tools do not follow the same conventions for command-line arguments. Strangely, kafka-producer-perf-test.sh  does not support the --bootstrap-server  argument which all of the other tools do, instead requiring --producer.props bootstrap.servers= (note the "s" on "bootstrap.servers" because it's the name of the producer config). This means that simple familiarity with the other tools isn't sufficient to get the command line for this tool correct without a little trial and error.

There are a few other inconsistencies where different names are used for the same thing in different tools. The differences just add a little friction when working with the tools.

Public Interfaces

This KIP makes changes to the arguments of some of the command-line tools. The proposed changes are:

• Add --bootstrap-server  to kafka-producer-perf-test.sh  bringing it into line with all the other tools. Because users will already have config files which specify the bootstrap server and there's no need to break these, the new --bootstrap-server  flag is optional. If provided, it takes precedence over specifying bootstrap.servers  in the configuration file. The order of precedence for configuring the bootstrap server from highest to lowest is --bootstrap-server , then --command-property (previously called --producer-props ), then --command-config .
• Introduce consistent use of --command-property  as a way of providing individual configuration properties without use of a configuration file. Replace --producer-props  with --command-property  in kafka-producer-perf-test.sh . Add --command-property  to kafka-consumer-perf-test.sh  and kafka-share-consumer-perf-test.sh .
• For the console producer and consumer tools, replace --producer-property  and --consumer-property  with --command-property .
• For all tools which support a properties file, replace the existing option for specifying a configuration properties file with --command-config  . This eliminates the guesswork about whether a particular tool uses the producer, consumer or admin APIs and then chose to pass this knowledge into the original names of the command-line arguments.
• Add --reporting-interval  to kafka-producer-perf-test.sh . The tools already has a reporting interval hard-coded to 5000ms, so this simply makes it configurable like for the consumer performance tests, with a default of 5000ms.
• Replace --property  with --formatter-property  in kafka-console-consumer.sh  and kafka-console-share-consumer.sh . This argument is used to configure the formatter, so this names it accordingly.
• Replace --property  with --reader-property  in kafka-console-producer.sh . This argument is used to configure the message reader, so this names it accordingly and also matches the existing --reader-config  argument.
• Replace  --messages  with --num-records  in kafka-consumer-perf-test.sh  and kafka-share-consumer-perf-test.sh .

Proposed Changes

The following table shows the existing and proposed options. The changes are in GREEN.

Compatibility, Deprecation, and Migration Plan

The existing options will be deprecated until the next major Apache Kafka release, and then they will be removed. During the deprecation period, using the old parameter names will cause a deprecation message to be displayed. It is an error to use both the old name and the new name together - they are mutually exclusive.

All uses of the command-line tools in the Apache Kafka codebase such as system tests will be migrated over to the new parameter names.

Test Plan

The KIP will be tested with unit tests.

For tests such as system tests which use these command-line tools, the tests will be migrated across to the new parameter names providing additional validation.

Rejected Alternatives

An alternative for tools such as kafka-verifiable-producer.sh  would be rename --producer.config  to --producer-config  instead of --command-config . This was rejected because some of the tools such as kafka-verifiable-share-consumer.sh  actually use multiple APIs (consumer and admin in this case) so the clean simplicity of --command-config  was chosen instead for all toolsIf 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.