omkafka: write to Apache Kafka

Broker

Specifies the broker(s) to use.

Topic

Specifies the topic to produce to.

Key

Kafka key to be used for all messages.

If a key is provided and partitions.auto=”on” is set, then all messages will be assigned to a partition based on the key.

DynaKey

If set, the key parameter becomes a template for the key to base the partitioning on.

DynaTopic

If set, the topic parameter becomes a template for which topic to produce messages to. The cache is cleared on HUP.

DynaTopic.Cachesize

If set, defines the number of topics that will be kept in the dynatopic cache.

Partitions.Auto

Librdkafka provides an automatic partitioning function that will automatically distribute the produced messages into all partitions configured for that topic.

To use, set partitions.auto=”on”. This is instead of specifying the number of partitions on the producer side, where it would be easier to change the kafka configuration on the cluster for number of partitions/topic vs on every machine talking to Kafka via rsyslog.

If no key is set, messages will be distributed randomly across partitions. This results in a very even load on all partitions, but does not preserve ordering between the messages.

If a key is set, a partition will be chosen automatically based on it. All messages with the same key will be sorted into the same partition, preserving their ordering. For example, by setting the key to the hostname, messages from a specific host will be written to one partition and ordered, but messages from different nodes will be distributed across different partitions. This distribution is essentially random, but stable. If the number of different keys is much larger than the number of partitions on the topic, load will be distributed fairly evenly.

If set, it will override any other partitioning scheme configured.

Partitions.number

If set, specifies how many partitions exists and activates load-balancing among them. Messages are distributed more or less evenly between the partitions. Note that the number specified must be correct. Otherwise, some errors may occur or some partitions may never receive data.

Partitions.useFixed

If set, specifies the partition to which data is produced. All data goes to this partition, no other partition is ever involved for this action.

errorFile

If set, messages that could not be sent and caused an error messages are written to the file specified. This file is in JSON format, with a single record being written for each message in error. The entry contains the full message, as well as Kafka error number and reason string.

The idea behind the error file is that the admin can periodically run a script that reads the error file and reacts on it. Note that the error file is kept open from when the first error occurred up until rsyslog is terminated or received a HUP signal.

statsFile

If set, the contents of the JSON object containing the full librdkafka statistics will be written to the file specified. The file will be updated based on the statistics.interval.ms confparam value, which must also be set.

ConfParam

Permits to specify Kafka options. Rather than offering a myriad of config settings to match the Kafka parameters, we provide this setting here as a vehicle to set any Kafka parameter. This has the big advantage that Kafka parameters that come up in new releases can immediately be used.

Note that we use librdkafka for the Kafka connection, so the parameters are actually those that librdkafka supports. As of our understanding, this is a superset of the native Kafka parameters.

TopicConfParam

In essence the same as confParam, but for the Kafka topic.

Template

Sets the template to be used for this action.

closeTimeout

Sets the time to wait in ms (milliseconds) for draining messages submitted to kafka-handle (provided by librdkafka) before closing it.

The maximum value of closeTimeout used across all omkafka action instances is used as librdkafka unload-timeout while unloading the module (for shutdown, for instance).

resubmitOnFailure

If enabled, failed messages will be resubmit automatically when kafka is able to send messages again. To prevent message loss, this option should be enabled.

Note: Messages that are rejected by kafka due to exceeding the maximum configured message size, are automatically dropped. These errors are not retriable.

KeepFailedMessages

If enabled, failed messages will be saved and loaded on shutdown/startup and resend after startup if the kafka server is able to receive messages again. This setting requires resubmitOnFailure to be enabled as well.

failedMsgFile

Filename where the failed messages should be stored into. Needs to be set when keepFailedMessages is enabled, otherwise failed messages won’t be saved.

statsName

The name assigned to statistics specific to this action instance. The supported set of statistics tracked for this action instance are submitted, acked, failures. See the Statistic Counter section for more details.

Set a single value

For example, to select “snappy” compression, you can use:

action(type="omkafka" topic="mytopic" confParam="compression.codec=snappy")

which is equivalent to:

action(type="omkafka" topic="mytopic" confParam=["compression.codec=snappy"])

Set multiple values

To specify multiple values, just use the bracket notation and create a comma-delimited list of values as shown here:

action(type="omkafka" topic="mytopic"
       confParam=["compression.codec=snappy",
                  "socket.timeout.ms=5",
                  "socket.keepalive.enable=true"]
      )

Copyright 2008-2023 Rainer Gerhards (Großrinderfeld), and Others.