Kafka入门二：API及配置项说明

Kafka-API及配置项说明

一.前言

    在这里对生产者和消费者的API做一些说明，在开发中按实际需求选择使用

二.Producer

    2.1 producer的实例化

        在新版本Kafka中，不再使用之前需要config类来读取配置信息

            ProducerConfig config = new ProducerConfig(properties);

            Producer producer = new Producer(config);

        而是直接在实例化时读取即可

            Producer producer = new KafkaProducer(properties);

    2.2 发送消息后可指定回调方法

producer.send(record, new Callback() {
    @Override
    public void onCompletion(RecordMetadata metaData, Exception exception) {
        if(null!=exception){// 发送异常记录异常信息
        LOG.error("Send message occurs exception.",exception);
        }
        if(null!=metaData){
        LOG.info(String.format("offset:%s,partition:%s",metaData.offset(),metaData.partition()));
        }
    }
});

    2.3 生产者策略配置

属性	类型	默认值	重要性	说明
boostrap.servers	list		high	用于建立与kafka集群连接的host/port组。数据将会在所有servers上均衡加载，不管哪些server是指定用于bootstrapping。这个列表仅仅影响初始化的hosts（用于发现全部的servers）。这个列表格式： host1:port1,host2:port2,... 因为这些server仅仅是用于初始化的连接，以发现集群所有成员关系（可能会动态的变化），这个列表不需要包含所有的servers（你可能想要不止一个server，尽管这样，可能某个server宕机了）。如果没有server在这个列表出现，则发送数据会一直失败，直到列表可用。
acks	string	1	high	producer需要server接收到数据之后发出的确认接收的信号，此项配置就是指procuder需要多少个这样的确认信号。此配置实际上代表了数据备份的可用性。以下设置为常用选项： （1）acks=0： 设置为0表示producer不需要等待任何确认收到的信息。副本将立即加到socket  buffer并认为已经发送。没有任何保障可以保证此种情况下server已经成功接收数据，同时重试配置不会发生作用（因为客户端不知道是否失败）回馈的offset会总是设置为-1； （2）acks=1： 这意味着至少要等待leader已经成功将数据写入本地log，但是并没有等待所有follower是否成功写入。这种情况下，如果follower没有成功备份数据，而此时leader又挂掉，则消息会丢失。 （3）acks=all： 这意味着leader需要等待所有备份都成功写入日志，这种策略会保证只要有一个备份存活就不会丢失数据。这是最强的保证。 （4）其他的设置，例如acks=2也是可以的，这将需要给定的acks数量，但是这种策略一般很少用。
buffer.memory	long	33554432	high	producer可以用来缓存数据的内存大小。如果数据产生速度大于向broker发送的速度，producer会阻塞或者抛出异常，以“block.on.buffer.full”来表明。 这项设置将和producer能够使用的总内存相关，但并不是一个硬性的限制，因为不是producer使用的所有内存都是用于缓存。一些额外的内存会用于压缩（如果引入压缩机制），同样还有一些用于维护请求。
compression.type	string	none	high	producer用于压缩数据的压缩类型。默认是无压缩。正确的选项值是none、gzip、snappy。 压缩最好用于批量处理，批量处理消息越多，压缩性能越好。
retries	int	0	high	设置大于0的值将使客户端重新发送任何数据，一旦这些数据发送失败。注意，这些重试与客户端接收到发送错误时的重试没有什么不同。允许重试将潜在的改变数据的顺序，如果这两个消息记录都是发送到同一个partition，则第一个消息失败第二个发送成功，则第二条消息会比第一条消息出现要早。
batch.size	int	16384	medium	producer将试图批处理消息记录，以减少请求次数。这将改善client与server之间的性能。这项配置控制默认的批量处理消息字节数。 不会试图处理大于这个字节数的消息字节数。 发送到brokers的请求将包含多个批量处理，其中会包含对每个partition的一个请求。 较小的批量处理数值比较少用，并且可能降低吞吐量（0则会仅用批量处理）。较大的批量处理数值将会浪费更多内存空间，这样就需要分配特定批量处理数值的内存大小。
client.id	string		medium	当向server发出请求时，这个字符串会发送给server。目的是能够追踪请求源头，以此来允许ip/port许可列表之外的一些应用可以发送信息。这项应用可以设置任意字符串，因为没有任何功能性的目的，除了记录和跟踪
linger.ms	long	0	medium	producer组将会汇总任何在请求与发送之间到达的消息记录一个单独批量的请求。通常来说，这只有在记录产生速度大于发送速度的时候才能发生。然而，在某些条件下，客户端将希望降低请求的数量，甚至降低到中等负载一下。这项设置将通过增加小的延迟来完成--即，不是立即发送一条记录，producer将会等待给定的延迟时间以允许其他消息记录发送，这些消息记录可以批量处理。这可以认为是TCP种Nagle的算法类似。这项设置设定了批量处理的更高的延迟边界：一旦我们获得某个partition的batch.size，他将会立即发送而不顾这项设置，然而如果我们获得消息字节数比这项设置要小的多，我们需要“linger”特定的时间以获取更多的消息。 这个设置默认为0，即没有延迟。设定linger.ms=5，例如，将会减少请求数目，但是同时会增加5ms的延迟。
max.request.size	int	1028576	medium	请求的最大字节数。这也是对最大记录尺寸的有效覆盖。注意：server具有自己对消息记录尺寸的覆盖，这些尺寸和这个设置不同。此项设置将会限制producer每次批量发送请求的数目，以防发出巨量的请求。
receive.buffer.bytes	int	32768	medium	TCP receive缓存大小，当阅读数据时使用
send.buffer.bytes	int	131072	medium	TCP send缓存大小，当发送数据时使用
timeout.ms	int	30000	medium	此配置选项控制server等待来自followers的确认的最大时间。如果确认的请求数目在此时间内没有实现，则会返回一个错误。这个超时限制是以server端度量的，没有包含请求的网络延迟
block.on.buffer.full	boolean	true	low	当我们内存缓存用尽时，必须停止接收新消息记录或者抛出错误。默认情况下，这个设置为真，然而某些阻塞可能不值得期待，因此立即抛出错误更好。设置为false则会这样：producer会抛出一个异常错误：BufferExhaustedException， 如果记录已经发送同时缓存已满
metadata.fetch.timeout.ms	long	60000	low	是指我们所获取的一些元素据的第一个时间数据。元素据包含：topic，host，partitions。此项配置是指当等待元素据fetch成功完成所需要的时间，否则会跑出异常给客户端。
metadata.max.age.ms	long	300000	low	以微秒为单位的时间，是在我们强制更新metadata的时间间隔。即使我们没有看到任何partition leadership改变。
metric.reporters	list	[]	low	类的列表，用于衡量指标。实现MetricReporter接口，将允许增加一些类，这些类在新的衡量指标产生时就会改变。JmxReporter总会包含用于注册JMX统计
metrics.num.samples	int	2	low	用于维护metrics的样本数
metrics.sample.window.ms	long	30000	low	metrics系统维护可配置的样本数量，在一个可修正的window  size。这项配置配置了窗口大小，例如。我们可能在30s的期间维护两个样本。当一个窗口推出后，我们会擦除并重写最老的窗口
recoonect.backoff.ms	long	10	low	连接失败时，当我们重新连接时的等待时间。这避免了客户端反复重连
retry.backoff.ms	long	100	low	在试图重试失败的produce请求之前的等待时间。避免陷入发送-失败的死循环中。

三.Consumer

    3.1订阅主题

        在实例化一个消费者之后，我们需要为该消费者订阅主题。一个消费者可以同时订阅多个
主题，通常我们可以以集合的形式指定多个主题，或者以正则表达式形式订阅特定模式的主题。

        Kafka 定义了以下 3 种订阅主题方法。

• subscribe(Collection<String> topics)方法，以集合形式指定消费者订阅的主题，通常我们用ArrayList。
• subscribe(Collection<String> topics, ConsumerRebalanceListener listener)方法，订阅主题时指定一个监听器，用于在消费者发生平衡操作时回调进行相应的业务处理。
• subscribe(Pattern pattern, ConsumerRebalanceListener listener)方法，以正则表达式形式指定匹配特定模式的主题。

        在回调接口ConsumerRebalanceListener中定义了两个回调方法：

1. onPartitionsRevoked(Collection<TopicPartition> partitions)：在这里我们可以提交偏移量操作以避免数据重复消费
2. onPartitionsAssigned(Collection<TopicPartition> partitions)：这个方法在平衡之后、消费者开始拉去消息之前被调用，一般在该方法中保证各消费者回滚到正确的偏移量，即重置各消费者消费偏移量。

    3.2订阅指定分区

        可以通过subscribe()方法订阅主题，也可以某些主题的特定分区。Kafka提供了assign(Collection<TopicPartition> partitions)方法来订阅指定分区。

        例如，我们指定消费者只订阅主题“test”的编号为0和1的分区：

consumer.assign(Arrays.asList(new TopicPartition("test", 0),new TopicPartition("test", 1) ));

        需要注意的是：通过subscribe()方法订阅主题具有消费者自动均衡的功能。在多线程条件下多个消费者进程根据分区策略自动分配消费者线程与分区的关系，当一个消费组的消费者发生增减变化时，分区分配关系会自动调整，以实现消费负载均衡及故障自动转移。而assign()方法订阅主题时，不具有消费者自动均衡的功能。

    3.3消费偏移量offset管理

        Kafka consumer-API提供了两个方法用于查询消费偏移量的操作

          一个是committed(TopicPartition partition)方法，该方法返回一个OffsetAndMetadata对象，通过OffsetAndMetadata对象可以获取指定分区已提交的偏移量；

            另一个是返回下一次拉取位置的position()方法。

        同时，consumer-API还提供了重置消费偏移量的方法：

            seek(TopicPartition partition, long offset)方法用于将消费起始位置重置到指定的偏移量位置

          seekToBeginning()和seekToEnd()，从名字上可以看出，前者指定从消息起始位置开始消费，对应偏移量重置策略auto.offset.reset=earliest; 后者指定从最新消息对应的位置开始消费，也就是说要等待新消息写入后才开始进行拉取，对应偏移量重置策略auto.offset.reset=latest。

    3.4消费者策略配置

属性	默认值	说明
group.id		用来唯一标识consumer进程所在组的字符串，如果设置同样的group  id，表示这些processes都是属于同一个consumer  group
zookeeper.connect		指定zookeeper的连接的字符串，格式是hostname：port，此处host和port都是zookeeper server的host和port，为避免某个zookeeper 机器宕机之后失联，你可以指定多个hostname：port，使用逗号作为分隔： hostname1：port1，hostname2：port2，hostname3：port3 可以在zookeeper连接字符串中加入zookeeper的chroot路径，此路径用于存放他自己的数据，方式： hostname1：port1，hostname2：port2，hostname3：port3/chroot/path
consumer.id	null	不需要设置，一般自动产生
socket.timeout.ms	30*100	网络请求的超时限制。真实的超时限制是   max.fetch.wait+socket.timeout.ms
socket.receive.buffer.bytes	64*1024	socket用于接收网络请求的缓存大小
fetch.message.max.bytes	1024*1024	每次fetch请求中，针对每次fetch消息的最大字节数。这些字节将会督导用于每个partition的内存中，因此，此设置将会控制consumer所使用的memory大小。这个fetch请求尺寸必须至少和server允许的最大消息尺寸相等，否则，producer可能发送的消息尺寸大于consumer所能消耗的尺寸。
num.consumer.fetchers	1	用于fetch数据的fetcher线程数
auto.commit.enable	true	如果为真，consumer所fetch的消息的offset将会自动的同步到zookeeper。这项提交的offset将在进程挂掉时，由新的consumer使用
auto.commit.interval.ms	60*1000	consumer向zookeeper提交offset的频率，单位是秒
queued.max.message.chunks	2	用于缓存消息的最大数目，以供consumption。每个chunk必须和fetch.message.max.bytes相同
rebalance.max.retries	4	当新的consumer加入到consumer  group时，consumers集合试图重新平衡分配到每个consumer的partitions数目。如果consumers集合改变了，当分配正在执行时，这个重新平衡会失败并重入
fetch.min.bytes	1	每次fetch请求时，server应该返回的最小字节数。如果没有足够的数据返回，请求会等待，直到足够的数据才会返回。
fetch.wait.max.ms	100	如果没有足够的数据能够满足fetch.min.bytes，则此项配置是指在应答fetch请求之前，server会阻塞的最大时间。
rebalance.backoff.ms	2000	在重试reblance之前backoff时间
refresh.leader.backoff.ms	200	在试图确定某个partition的leader是否失去他的leader地位之前，需要等待的backoff时间
auto.offset.reset	largest	zookeeper中没有初始化的offset时，如果offset是以下值的回应： smallest：自动复位offset为smallest的offset largest：自动复位offset为largest的offset anything  else：向consumer抛出异常
consumer.timeout.ms	-1	如果没有消息可用，即使等待特定的时间之后也没有，则抛出超时异常
exclude.internal.topics	true	是否将内部topics的消息暴露给consumer
paritition.assignment.strategy	range	选择向consumer 流分配partitions的策略，可选值：range，roundrobin
client.id	group id value	是用户特定的字符串，用来在每次请求中帮助跟踪调用。它应该可以逻辑上确认产生这个请求的应用
zookeeper.session.timeout.ms	6000	zookeeper 会话的超时限制。如果consumer在这段时间内没有向zookeeper发送心跳信息，则它会被认为挂掉了，并且reblance将会产生
zookeeper.connection.timeout.ms	6000	客户端在建立通zookeeper连接中的最大等待时间
zookeeper.sync.time.ms	2000	ZK follower可以落后ZK leader的最大时间
offsets.storage	zookeeper	用于存放offsets的地点： zookeeper或者kafka
offset.channel.backoff.ms	1000	重新连接offsets channel或者是重试失败的offset的fetch/commit请求的backoff时间
offsets.channel.socket.timeout.ms	10000	当读取offset的fetch/commit请求回应的socket 超时限制。此超时限制是被consumerMetadata请求用来请求offset管理
offsets.commit.max.retries	5	重试offset commit的次数。这个重试只应用于offset  commits在shut-down之间。他
dual.commit.enabled	true	如果使用“kafka”作为offsets.storage，你可以二次提交offset到zookeeper(还有一次是提交到kafka）。在zookeeper-based的offset  storage到kafka-based的offset storage迁移时，这是必须的。对任意给定的consumer  group来说，比较安全的建议是当完成迁移之后就关闭这个选项
partition.assignment.strategy	range	在“range”和“roundrobin”策略之间选择一种作为分配partitions给consumer 数据流的策略； 循环的partition分配器分配所有可用的partitions以及所有可用consumer  线程。它会将partition循环的分配到consumer线程上。如果所有consumer实例的订阅都是确定的，则partitions的划分是确定的分布。循环分配策略只有在以下条件满足时才可以：（1）每个topic在每个consumer实力上都有同样数量的数据流。（2）订阅的topic的集合对于consumer  group中每个consumer实例来说都是确定的。