The Kafka connector receives serialized data from the export tables and writes it to a message queue using the Apache Kafka version 0.8 protocols. Apache Kafka is a distributed messaging service that lets you set up message queues which are written to and read from by "producers" and "consumers", respectively. In the Apache Kafka model, VoltDB export acts as a "producer".

Before using the Kafka connector, we strongly recommend reading the Kafka documentation and becoming familiar with the software, since you will need to set up a Kafka 0.8 service and appropriate "consumer" clients to make use of VoltDB's Kafka export functionality. The instructions in this section assume a working knowledge of Kafka and the Kafka operational model.

When the Kafka connector receives data from the VoltDB export tables, it establishes a connection to the Kafka messaging service as a Kafka producer. It then writes records to the service using the VoltDB table name and a predetermined prefix as the Kafka "topic". How and when the data is transmitted to Kafka and the name of the topic prefix are controlled by the export connector properties.

The majority of the Kafka properties are identical in both in name and content to the Kafka producer properties listed in the Kafka documentation. All but one of these properties are optional for the Kafka connector and will use the standard Kafka default value. For example, if you do not specify the queue.buffering.max.ms property it defaults to 5000 milliseconds.

The only required property is metadata.broker.list, which lists the Kafka servers that the VoltDB export connector should connect to. You must specify this property so VoltDB knows where to send the export data.

In addition to the standard Kafka producer properties, there are several custom properties specific to VoltDB. The properties binaryencoding, skipinternals, and timezone affect the format of the data. The topic.prefix and batch.mode properties affect how and when the data is written to Kafka.

The topic.prefix property specifies the text that precedes the table name when constructing the Kafka topic. If you do not specify a prefix, it defaults to "voltdbexport". Note that unless you configure the Kafka brokers with the auto.create.topics.enable property set to true, you must create the topics for every export table manually before starting the export process. Enabling auto-creation of topics when setting up the Kafka brokers is recommended.

The batch.mode property specifies whether messages are sent in batches, like the JDBC connector, or one message at a time. When configuring the export connector, it is important to understand the relationship between batch mode and synchronous versus asynchronous processing and their effect on database latency.

Using batch mode reduces the number of packets that must be sent to the Kafka servers, optimizing network bandwidth. If the export data is sent asynchronously, by setting the property producer.type to "async", the impact of export on the database is further reduced, since the export connector does not wait for the Kafka server to respond. However, with asynchronous processing, VoltDB is not able to resend the data if the message fails after it is sent.

If export to Kafka is done synchronously, the export connector waits for acknowledgement of each message sent to the Kafka server before processing the next packet. This allows the connector to resend any packets that fail. The drawback to synchronous processing is that on a heavily loaded database, the latency it introduces means export may not be able to keep up with the influx of export data and and have to write to overflow.

VoltDB guarantees that at least one copy of all export data is sent by the export connector. But when operating in asynchronous mode, the Kafka connector cannot guarantee that the packet is actually received and accepted by the Kafka broker. By operating in synchronous mode, VoltDB can catch errors returned by the Kafka broker and resend any failed packets. However, you pay the penalty of additional latency and possible export overflow.

To balance performance with durability of the exported data, the following are the two recommended configurations for producer type and batch mode:

Finally, the actual export data is sent to Kafka as a comma-separated values (CSV) formatted string. The message includes six columns of metadata (such as the transaction ID and timestamp) followed by the column values of the export table.

Table 13.4, “Kafka Export Properties” lists the supported properties for the Kafka connector, including the standard Kafka producer properties and the VoltDB unique properties.