:integration: kafka
:plugin: kafka
:type: output
:default_codec: plain
:kafka_client: 3.4
:kafka_client_doc: 34

///////////////////////////////////////////
START - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////
:version: %VERSION%
:release_date: %RELEASE_DATE%
:changelog_url: %CHANGELOG_URL%
:include_path: ../../../../logstash/docs/include
///////////////////////////////////////////
END - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////

[id="plugins-{type}s-{plugin}"]

=== Kafka output plugin

include::{include_path}/plugin_header-integration.asciidoc[]

==== Description

Write events to a Kafka topic. 

This plugin uses Kafka Client {kafka_client}. For broker compatibility, see the
official
https://cwiki.apache.org/confluence/display/KAFKA/Compatibility+Matrix[Kafka
compatibility reference]. If the linked compatibility wiki is not up-to-date,
please contact Kafka support/community to confirm compatibility.

If you require features not yet available in this plugin (including client
version upgrades), please file an issue with details about what you need.

This output supports connecting to Kafka over:

* SSL (requires plugin version 3.0.0 or later)
* Kerberos SASL (requires plugin version 5.1.0 or later)

By default security is disabled but can be turned on as needed.

The only required configuration is the topic_id. 

The default codec is plain. Logstash will encode your events with not only the
message field but also with a timestamp and hostname.

If you want the full content of your events to be sent as json, you should set
the codec in the output configuration like this:

[source,ruby]
    output {
      kafka {
        codec => json
        topic_id => "mytopic"
      }
    }
    
For more information see
https://kafka.apache.org/{kafka_client_doc}/documentation.html#theproducer

Kafka producer configuration:
https://kafka.apache.org/{kafka_client_doc}/documentation.html#producerconfigs

NOTE:  This plugin does not support using a proxy when communicating to the Kafka broker.

[id="plugins-{type}s-{plugin}-options"]
==== Kafka Output Configuration Options

This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.

NOTE: Some of these options map to a Kafka option. Defaults usually reflect the Kafka default setting,
and might change if Kafka's producer defaults change.
See the https://kafka.apache.org/{kafka_client_doc}/documentation for more details.

[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-acks>> |<<string,string>>, one of `["0", "1", "all"]`|No
| <<plugins-{type}s-{plugin}-batch_size>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-bootstrap_servers>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-buffer_memory>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-client_dns_lookup>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-client_id>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-compression_type>> |<<string,string>>, one of `["none", "gzip", "snappy", "lz4", "zstd"]`|No
| <<plugins-{type}s-{plugin}-connections_max_idle_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-jaas_path>> |a valid filesystem path|No
| <<plugins-{type}s-{plugin}-kerberos_config>> |a valid filesystem path|No
| <<plugins-{type}s-{plugin}-key_serializer>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-linger_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-max_request_size>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-message_key>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-metadata_fetch_timeout_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-metadata_max_age_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-partitioner>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-receive_buffer_bytes>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-reconnect_backoff_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-request_timeout_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-retries>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-retry_backoff_ms>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-sasl_jaas_config>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-sasl_kerberos_service_name>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-sasl_mechanism>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-security_protocol>> |<<string,string>>, one of `["PLAINTEXT", "SSL", "SASL_PLAINTEXT", "SASL_SSL"]`|No
| <<plugins-{type}s-{plugin}-send_buffer_bytes>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-ssl_endpoint_identification_algorithm>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-ssl_key_password>> |<<password,password>>|No
| <<plugins-{type}s-{plugin}-ssl_keystore_location>> |a valid filesystem path|No
| <<plugins-{type}s-{plugin}-ssl_keystore_password>> |<<password,password>>|No
| <<plugins-{type}s-{plugin}-ssl_keystore_type>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-ssl_truststore_location>> |a valid filesystem path|No
| <<plugins-{type}s-{plugin}-ssl_truststore_password>> |<<password,password>>|No
| <<plugins-{type}s-{plugin}-ssl_truststore_type>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-topic_id>> |<<string,string>>|Yes
| <<plugins-{type}s-{plugin}-value_serializer>> |<<string,string>>|No
|=======================================================================

Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
output plugins.

&nbsp;

[id="plugins-{type}s-{plugin}-acks"]
===== `acks` 

  * Value can be any of: `0`, `1`, `all`
  * Default value is `"1"`

The number of acknowledgments the producer requires the leader to have received
before considering a request complete.

`acks=0`. The producer will not wait for any acknowledgment from the server.

`acks=1`. The leader will write the record to its local log, but will respond
without waiting for full acknowledgement from all followers.
          
`acks=all`. The leader will wait for the full set of in-sync replicas before
acknowledging the record.

[id="plugins-{type}s-{plugin}-batch_size"]
===== `batch_size` 

  * Value type is <<number,number>>
  * Default value is `16384`.

The producer will attempt to batch records together into fewer requests whenever multiple
records are being sent to the same partition. This helps performance on both the client
and the server. This configuration controls the default batch size in bytes.

[id="plugins-{type}s-{plugin}-bootstrap_servers"]
===== `bootstrap_servers` 

  * Value type is <<string,string>>
  * Default value is `"localhost:9092"`

This is for bootstrapping and the producer will only use it for getting metadata (topics,
partitions and replicas). The socket connections for sending the actual data will be
established based on the broker information returned in the metadata. The format is
`host1:port1,host2:port2`, and the list can be a subset of brokers or a VIP pointing to a
subset of brokers.

[id="plugins-{type}s-{plugin}-buffer_memory"]
===== `buffer_memory` 

  * Value type is <<number,number>>
  * Default value is `33554432` (32MB).

The total bytes of memory the producer can use to buffer records waiting to be sent to the server.

[id="plugins-{type}s-{plugin}-client_dns_lookup"]
===== `client_dns_lookup` 

  * Value type is <<string,string>>
  * Valid options are `use_all_dns_ips`, `resolve_canonical_bootstrap_servers_only`, `default`
  * Default value is `"default"`

Controls how DNS lookups are done. If set to `use_all_dns_ips`, Logstash tries
all IP addresses returned for a hostname before failing the connection.
If set to `resolve_canonical_bootstrap_servers_only`, each entry will be 
resolved and expanded into a list of canonical names.

[NOTE]
====
Starting from Kafka 3 `default` value for `client.dns.lookup` value has been removed.
If explicitly configured it fallbacks to `use_all_dns_ips`.
====

[id="plugins-{type}s-{plugin}-client_id"]
===== `client_id` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

The id string to pass to the server when making requests.
The purpose of this is to be able to track the source of requests beyond just
ip/port by allowing a logical application name to be included with the request

[id="plugins-{type}s-{plugin}-compression_type"]
===== `compression_type` 

  * Value can be any of: `none`, `gzip`, `snappy`, `lz4`, `zstd`
  * Default value is `"none"`

The compression type for all data generated by the producer.
The default is none (meaning no compression). Valid values are none, gzip, snappy, lz4, or zstd.

[id="plugins-{type}s-{plugin}-connections_max_idle_ms"]
===== `connections_max_idle_ms`

  * Value type is <<number,number>>
  * Default value is `540000` milliseconds (9 minutes).

Close idle connections after the number of milliseconds specified by this config.

[id="plugins-{type}s-{plugin}-jaas_path"]
===== `jaas_path` 

  * Value type is <<path,path>>
  * There is no default value for this setting.

The Java Authentication and Authorization Service (JAAS) API supplies user authentication and authorization 
services for Kafka. This setting provides the path to the JAAS file. Sample JAAS file for Kafka client:
[source,java]
----------------------------------
KafkaClient {
  com.sun.security.auth.module.Krb5LoginModule required
  useTicketCache=true
  renewTicket=true
  serviceName="kafka";
  };
----------------------------------

Please note that specifying `jaas_path` and `kerberos_config` in the config file will add these 
to the global JVM system properties. This means if you have multiple Kafka inputs, all of them would be sharing the same 
`jaas_path` and `kerberos_config`. If this is not desirable, you would have to run separate instances of Logstash on 
different JVM instances.

[id="plugins-{type}s-{plugin}-kerberos_config"]
===== `kerberos_config` 

  * Value type is <<path,path>>
  * There is no default value for this setting.

Optional path to kerberos config file. This is krb5.conf style as detailed in https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html

[id="plugins-{type}s-{plugin}-key_serializer"]
===== `key_serializer` 

  * Value type is <<string,string>>
  * Default value is `"org.apache.kafka.common.serialization.StringSerializer"`

Serializer class for the key of the message

[id="plugins-{type}s-{plugin}-linger_ms"]
===== `linger_ms` 

  * Value type is <<number,number>>
  * Default value is `0`

The producer groups together any records that arrive in between request
transmissions into a single batched request. Normally this occurs only under
load when records arrive faster than they can be sent out. However in some circumstances
the client may want to reduce the number of requests even under moderate load.
This setting accomplishes this by adding a small amount of artificial delay—that is,
rather than immediately sending out a record the producer will wait for up to the given delay
to allow other records to be sent so that the sends can be batched together.

[id="plugins-{type}s-{plugin}-max_request_size"]
===== `max_request_size` 

  * Value type is <<number,number>>
  * Default value is `1048576` (1MB).

The maximum size of a request

[id="plugins-{type}s-{plugin}-message_key"]
===== `message_key` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

The key for the message.

[id="plugins-{type}s-{plugin}-metadata_fetch_timeout_ms"]
===== `metadata_fetch_timeout_ms` 

  * Value type is <<number,number>>
  * Default value is `60000` milliseconds (60 seconds).

The timeout setting for initial metadata request to fetch topic metadata.

[id="plugins-{type}s-{plugin}-metadata_max_age_ms"]
===== `metadata_max_age_ms` 

  * Value type is <<number,number>>
  * Default value is `300000` milliseconds (5 minutes).

The max time in milliseconds before a metadata refresh is forced.

[id="plugins-{type}s-{plugin}-partitioner"]
===== `partitioner`

* Value type is <<string,string>>
* There is no default value for this setting.

The default behavior is to hash the `message_key` of an event to get the partition.
When no message key is present, the plugin picks a partition in a round-robin fashion.

Available options for choosing a partitioning strategy are as follows:

* `default` use the default partitioner as described above
* `round_robin` distributes writes to all partitions equally, regardless of `message_key`
* `uniform_sticky` sticks to a partition for the duration of a batch than randomly picks a new one

[id="plugins-{type}s-{plugin}-receive_buffer_bytes"]
===== `receive_buffer_bytes` 

  * Value type is <<number,number>>
  * Default value is `32768` (32KB).

The size of the TCP receive buffer to use when reading data

[id="plugins-{type}s-{plugin}-reconnect_backoff_ms"]
===== `reconnect_backoff_ms` 

  * Value type is <<number,number>>
  * Default value is `50`.

The amount of time to wait before attempting to reconnect to a given host when a connection fails.

[id="plugins-{type}s-{plugin}-request_timeout_ms"]
===== `request_timeout_ms` 

  * Value type is <<number,number>>
  * Default value is `40000` milliseconds (40 seconds).

The configuration controls the maximum amount of time the client will wait
for the response of a request. If the response is not received before the timeout
elapses the client will resend the request if necessary or fail the request if
retries are exhausted.

[id="plugins-{type}s-{plugin}-retries"]
===== `retries` 

  * Value type is <<number,number>>
  * There is no default value for this setting.

The default retry behavior is to retry until successful. To prevent data loss,
the use of this setting is discouraged.

If you choose to set `retries`, a value greater than zero will cause the
client to only retry a fixed number of times. This will result in data loss
if a transport fault exists for longer than your retry count (network outage,
Kafka down, etc).

A value less than zero is a configuration error.

Starting with version 10.5.0, this plugin will only retry exceptions that are a subclass of
https://kafka.apache.org/{kafka_client_doc}/javadoc/org/apache/kafka/common/errors/RetriableException.html[RetriableException]
and
https://kafka.apache.org/{kafka_client_doc}/javadoc/org/apache/kafka/common/errors/InterruptException.html[InterruptException].
If producing a message throws any other exception, an error is logged and the message is dropped without retrying.
This prevents the Logstash pipeline from hanging indefinitely.

In versions prior to 10.5.0, any exception is retried indefinitely unless the `retries` option is configured.

[id="plugins-{type}s-{plugin}-retry_backoff_ms"]
===== `retry_backoff_ms` 

  * Value type is <<number,number>>
  * Default value is `100` milliseconds.

The amount of time to wait before attempting to retry a failed produce request to a given topic partition.

[id="plugins-{type}s-{plugin}-sasl_jaas_config"]
===== `sasl_jaas_config` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

JAAS configuration setting local to this plugin instance, as opposed to settings using config file configured using `jaas_path`, which are shared across the JVM. This allows each plugin instance to have its own configuration. 

If both `sasl_jaas_config` and `jaas_path` configurations are set, the setting here takes precedence.

Example (setting for Azure Event Hub):
[source,ruby]
    output {
      kafka {
        sasl_jaas_config => "org.apache.kafka.common.security.plain.PlainLoginModule required username='auser'  password='apassword';"
      }
    }

[id="plugins-{type}s-{plugin}-sasl_kerberos_service_name"]
===== `sasl_kerberos_service_name` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

The Kerberos principal name that Kafka broker runs as. 
This can be defined either in Kafka's JAAS config or in Kafka's config.

[id="plugins-{type}s-{plugin}-sasl_mechanism"]
===== `sasl_mechanism` 

  * Value type is <<string,string>>
  * Default value is `"GSSAPI"`

http://kafka.apache.org/documentation.html#security_sasl[SASL mechanism] used for client connections. 
This may be any mechanism for which a security provider is available.
GSSAPI is the default mechanism.

[id="plugins-{type}s-{plugin}-security_protocol"]
===== `security_protocol` 

  * Value can be any of: `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL`
  * Default value is `"PLAINTEXT"`

Security protocol to use, which can be either of PLAINTEXT,SSL,SASL_PLAINTEXT,SASL_SSL

[id="plugins-{type}s-{plugin}-send_buffer_bytes"]
===== `send_buffer_bytes` 

  * Value type is <<number,number>>
  * Default value is `131072` (128KB).

The size of the TCP send buffer to use when sending data.

[id="plugins-{type}s-{plugin}-ssl_endpoint_identification_algorithm"]
===== `ssl_endpoint_identification_algorithm`

  * Value type is <<string,string>>
  * Default value is `"https"`

The endpoint identification algorithm, defaults to `"https"`. Set to empty string `""` to disable

[id="plugins-{type}s-{plugin}-ssl_key_password"]
===== `ssl_key_password` 

  * Value type is <<password,password>>
  * There is no default value for this setting.

The password of the private key in the key store file.

[id="plugins-{type}s-{plugin}-ssl_keystore_location"]
===== `ssl_keystore_location` 

  * Value type is <<path,path>>
  * There is no default value for this setting.

If client authentication is required, this setting stores the keystore path.

[id="plugins-{type}s-{plugin}-ssl_keystore_password"]
===== `ssl_keystore_password` 

  * Value type is <<password,password>>
  * There is no default value for this setting.

If client authentication is required, this setting stores the keystore password

[id="plugins-{type}s-{plugin}-ssl_keystore_type"]
===== `ssl_keystore_type` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

The keystore type.

[id="plugins-{type}s-{plugin}-ssl_truststore_location"]
===== `ssl_truststore_location` 

  * Value type is <<path,path>>
  * There is no default value for this setting.

The JKS truststore path to validate the Kafka broker's certificate.

[id="plugins-{type}s-{plugin}-ssl_truststore_password"]
===== `ssl_truststore_password` 

  * Value type is <<password,password>>
  * There is no default value for this setting.

The truststore password

[id="plugins-{type}s-{plugin}-ssl_truststore_type"]
===== `ssl_truststore_type` 

  * Value type is <<string,string>>
  * There is no default value for this setting.

The truststore type.

[id="plugins-{type}s-{plugin}-topic_id"]
===== `topic_id` 

  * This is a required setting.
  * Value type is <<string,string>>
  * There is no default value for this setting.

The topic to produce messages to

[id="plugins-{type}s-{plugin}-value_serializer"]
===== `value_serializer` 

  * Value type is <<string,string>>
  * Default value is `"org.apache.kafka.common.serialization.StringSerializer"`

Serializer class for the value of the message



[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]

:default_codec!:
