一、性能

librdkafka库是多线程的，给现在硬件系统设计，并尽力实现最小的内存拷贝。生产或消费的消息的payload在传输中没有拷贝，同时消息的尺寸没有任何限制。

“你可能需要高吞吐率或者低延迟，但你可以拥有这两个性能”。

librdkafka 允许你实现高吞吐率或者低延迟，这是通过可配置的属性设置实现的。

性能指标中最重要的两个配置属性是：

-batch.num.messages：在发送消息序列之前，本地消息队列中需要积累的最小消息数。

-queue.buffering.max.ms：等待batch.num.messags在本地队列中实现的时间长度。

1、性能指标

后面的测试都是使用以下性能配置指标：

-intel  Quad  Core i7  at 3.4GHz， 8GB 内存

-通过设置brokers 刷新的配置属性，采用简单的方式测试硬盘性能。

       log.flush.interval.messages=10000000

      log.flush.interval.ms=100000

-两个brokers和librdkafka都运行在同一台机器上

-每个topic有两个partitions

-每个broker只是一个partitions的leader

-使用子目录example下的rdkafka_performance进行测试

测试结果（注意，原文只有producer的测试）

Test1: 2 brokers, 2 partitions, required.acks=2, 100 byte messages: 850000 messages/second, 85 MB/second

Test2: 1 broker, 1 partition, required.acks=0, 100 byte messages: 710000 messages/second, 71 MB/second

Test3: 2 broker2, 2 partitions, required.acks=2, 100 byte messages, snappy compression: 300000 messages/second, 30 MB/second

Test4: 2 broker2, 2 partitions, required.acks=2, 100 byte messages, gzip compression: 230000 messages/second, 23 MB/second

注意：本文最后将描述详细的测试信息

注意：consumer的测试结果很快就会补上

2、高吞吐率

高吞吐率的关键是消息批处理实现--首先本地消息队列中会积累一定数量的消息，然后再将这些消息一块发送出去。这就减少了消息传递消耗并且减少了来回申请产生不良影响。

默认设置下： batch.num.messages=1000，queue.buffering.max.ms=1000,这有利于高吞吐率。默认设置使得librdkafka向broker发送累积消息之前，可以等待1000ms，消息最多累积1000条。这两个属性哪一个先满足，就停止消息累积并进行发送，无论另一个属性是否满足。

这些设置虽然是全局性的（在rd_kafka_conf_t结构中实现），但是却适用于每个top+partitions基本组成。

3、低延迟

当要求消息发送低延迟时，“queue.buffering.max.ms"应当符合producer-side延迟所允许的最大值。 queue.buffering.max.ms设置为0将使得消息尽可能快的发送。

3、压缩

Producer 消息压缩通过“compression.codec配置属性实现。

压缩是批处理本地队列中的消息的，批处理消息的数目越大，压缩率越高。本地批处理队列的容量取决于”batch.num.messages“”queue.buffering.max.ms"配置属性，这在上边高吞吐率章节讨论。

二、消息可靠性

消息可靠性是librdkafka重要指标----实际应用中可以通过两个特定设置（“reuqest.required.acks”和“message.send.max.retries”）保证消息可靠性。

如果topic配置属性"request.reuired.acks“（除了0之外的其他值，查看具体细节）设置用来等待brokers收到消息的确认回复，则librdkafka在收到所有预期acks之前会一直保存消息，这就可以很好的处理一下事件：

-brokers 连接失败

-topic leader发生变化

-brokers通知produce错误

这些都是librdkafka自动完成，具体应用中无需针对以上事件做任何处理。消息在收到失败反馈之前可以保有的时间为”message.send.max.retires"。

librdkafka使用回调函数应对不同发送报告，即应对不同的消息发送状态，它将在收到每条消息传送状态时调用响应的回调函数。

-如果error_code  非0，则消息发送失败，error_code指明失败原因（rd_kafka_resp_err_t enum）

-如果error_code 为0，则消息成功发送

更多细节需要查看Producer  API章节。

发送报告的回调函数是可选的。

三、用法

1、文档介绍

librdkafka API描述在rdkafka.h中，配置属性描述在CONFIGURATION.md。

2、初始化

实际应用中，需要创建一个top-level的对象 rd_kafka_t， 这个对象是基本的容器，它提供了全局性配置属性以及共享状态信息，它由rd_kafka_new()函数创建。

同时也需要创建一个或者多个topics对象rd_kafka_topic_t，给produer以及consumer使用。 topic对象具有topic特定的配置属性，同时还包含了所有可用partitions与leader  brokers映射关系。它通过调用rd_kafka_topic_new()函数创建。

这两个对象都包含了可配置的API。默认情况下将调用默认值，具体属性默认值描述在CONFIGURATION.md。

注意：实际应用中，可能会创建多个rd_kafka_t对象，它们并没有共享状态信息

注意：rd_kafka_topic_t对象只能由创建它的对象rd_kafka_t使用。

3、配置

为了简化与kafka的集成以及缩短学习曲线，librdkafka实现配置属性都可以在kafka官方客户端中找到。

在创建对象之前，需要使用rd_kafka_conf_set()以及rd_kafka_topic_conf_set()函数进行配置。

注意： rd_kafka.._conf_t对象们在rd_kafka.._new()函数使用过后是不能被再次使用的，而且在rd_kakfa.._new()函数调用之后，不需要释放配置资源。

4、线程和回调函数

librdkafka 内部将会有多个线程，以充分利用硬件资源。API的实现是完全线程安全的，实际应用中可以在任何时候任何线程中调用任何API函数而不用担心线程安全。

一个以轮询为基础的API用来给实际应用提供信号反馈，实际应用应当按照固定时间间隔调用rd_kafka_poll()函数。这个轮询的API将会调用以下可的回调（都是可选的）：

-消息发送报告回调：报告消息发送失败。这将允许实际应用采取措施应对发送失败，并释放消息发送过程中占有的资源。

-错误回调：报告错误；错误一般是信息化方面的，例如连接broker失败，实际应用通常不需要采取任何措施。错误的数据类型是通过rd_kafka_resp_err_t enum类型数据，可以描述本地错误和远程broker错误。

不是poll函数引起的可选回调函数，可能是由任意线程引发的：

-logging 回调：实际应用中，用于发送librdkafka产生的log消息。

-partitioner 回调：实际应用提供消息的partitioner。partitioner可能被任何线程任何时候调用，它可能由于同一个key而被调用多次。Partitioner 函数有以下限制：

     一定不能调用rd_kafka_*()等函数

     一定不能阻塞或延长执行

      一定要返回一个0到partition_cnt-1之间的值，或者是在partitioning不能执行的时候返回特定RD_KAFKA_PARTITION_UA值，

5、Brokers

librdkafka 只需要一份最初的brokers列表（至少包含一个broker）。它将连接所有"metadata.broker.list"或者是rd_kafka_brokers_add()函数添加的brokers，然后向每个brokers申请一些元数据信息：包含brokers的完整列表、topic、partitions以及它们在Kafka 集群中的leaders broker信息。

Brokers名字的形式为：host：port； 其中port是可选的，默认是9092，host是任何一个可以解析的hostname或者ipv4或者ipv6地址。如果host是多个地址，librdkafka将会在每一次连接尝试中循环连接这些地址。包含所有broker 地址的DNS记录可以用来提供可靠的bootstrap broker。

6、Producer  API

在使用RD_KAFKA_PRODUCER设置完rd_kafka_t对象后，就可以创建一个或者多个rd_kafka_topic_t对象了，用来接受信息或者发送信息。

rd_kafka_produce()函数需要以下参数：

-rkt： topic， 由前面rd_kafka_topic_new()函数创建

-partition：partition，如果为RD_KAFKA_PARTITION_UA，则配置的partitioner函数将会选择目标partition

-payload，len： 消息主体

-msgflags：0或者以下数值之一：

                   RD_KAFKA_MSG_F_COPY: librdkafka 在发送前先将消息拷贝下来，以防消息主体所在的缓存不是长久使用的，例如堆栈。

                   RD_KAFKA_MSG_F_FREE: librdkafka 在使用完消息后，将释放消息缓存。

                   这两个标志是互斥的，只能设置一个，用来表示是拷贝还是释放。

                    如果没有设置RD_KAFKA_MSG_F_COPY标志，则没有数据拷贝，librdkafka将会占有消息payload指针直到消息发送完毕或者失败。发送报告回调函数将会在librdkafka使实际调用重新获得payload缓存控制权的时候被调用。在RD_KAFKA_MSG_F_FREE设置的时候，实际调用一定不能在发送报告回调函数中释放payload。

-key，keylen： 可选参数，消息关键字，可以用来分区。它将会传递到topic partitioner回调中，如果存在，则会添加到发向broker的消息中。

-msg_opaque：可选参数，每条消息的透明度指针，由消息传送回调所提供，使应用参考特定的消息。

rd_kafka_produce()是非阻塞的API， 它将使消息存储在内部队列中并立即返回。如果入队的消息数目超过了配置的“queue.buffering.max.messages"属性，则rd_kafka_produce()函数将会返回-1并将errno设置为ENOBUFS， 这样就提供了应对压力的机制。

注意：examples/rdkafka_performance.c提供了producer的实现。

7、Consumer  API

consumer API要比producer  API多一些状态。 在使用RD_KAFKA_CONSUMER类型创建rd_kafka_t 对象，然后创建rd_kakfa_topic_t对象之后，实际应用中必须调用rd_kafka_consumer_start()函数启动对给定partition的consumer。

rd_kafka_consume_start()函数的参数：

-rkt： 进行consume的topic， 由前面rd_kafka_topic_new()创建

-partition：进行consume的partition

-offset：开始consume的消息偏移。这个偏移可能是一个绝对消息偏移，或者是RD_KAKFA_OFFSET_STORED来使用存储的offset，也可能是两个特定偏移之一：RD_KAFKA_OFFSET_BEGINNING，从partition消息队列的开始进行consume；RD_KAFKA_OFFSET_END：从partition中的将要produce的下一条信息开始（忽略即当前所有的消息）。

在topic+partition的consumer启动之后，librdkafka将尝试使本地消息队列中的消息数目保持在queued.min.messages，一方反复的从broker获取消息。

本地消息队列将通过以下三种不同的consum  APIs进行consume：

-rd_kafka_consume()：每次consume一条消息

-rd_kafka_consume_batch()：批处理consume，一条或多条

-rd_kafka_consume_callback()：consume本地消息队列中的所有消息，并调用回调函数处理每条消息

上述三种方式按照性能排列的，rd_kafka_consume()是最慢的，rd_kafka_consume_callback()最快。不同的需求可以选择不同的实现方式。

一条consumed消息，由每一个consume函数提供或返回，具体是由rd_kafka_messag_t类型对象保存。

rd_kafka_message_t对象成员：

-err：错误返回值。非0值表示出现错误，err是rd_kafka_resp_err_t类型数据。如果是0则表示进行了适当的消息抓取，并且payload中包含了message。

-rkt，partition：topic和partition信息

-payload，len：消息的payload数据或者错误的消息（err！=0）

-key，key_len：可选参数，主要是用来获取特定的消息。

-offset：消息的偏移地址

payload，key和消息一样，都是属于librdkafka，在rd_kafka_message_destroy()函数调用之后就不能再使用了。librdkafka将会使用相同的消息集接收缓存来存放消息消息集的playloads，这就避免过度拷贝，即意味着如果实际应用决定挂起某个单独的rd_kafka_message_t对象，这将会阻碍后面的缓存释放。

当实际应用完成consume消息，则应该调用rd_kafka_consume_stop()函数停止consumer。这将消除本地队列中中任何消息。

注意：examples/rdkafka_performance.c实现了consumer。

8、offset 管理

Offset管理可以通过本地offset保存文件完成，offset将会周期性的写入每个topic+partition的配置属性：

-auto.commit.enable

-auto.commit.interval.ms

-offset.store.path

-offset.store.sync.interval.ms

当前ZooKeeper还不支持offset管理。

9、Consumer  groups

当前还不支持consumer  groups， librdkafka consumer  API只编译了官方scala 简单版的Consumer。只有librdkafka能够支持这项应用，你才能拥有你的消费组。

10、Topics

Topic自动创建

topic自动创建是支持的。brokers需要使用”auto.create.topics.enable=true“进行配置。

四、其他：

文章源地址：https://github.com/edenhill/librdkafka/blob/master/INTRODUCTION.md