CONFIGURATION.md

Client global configs

C/P legend: C = Consumer, P = Producer, * = both

Property	C/P	Range	Default	Description
builtin_features	*		gzip, snappy, ssl, sasl, regex, lz4, sasl_gssapi, sasl_plain, sasl_scram, plugins, zstd, sasl_oauthbearer	Indicates the builtin features for this build of librdkafka. An application can either query this value or attempt to set it with its list of required features to check for library support.
client_id	*		rdkafka	Client identifier
bootstrap_servers	*			Initial list of brokers host:port separated by comma
connections_max_idle_ms	*	0 .. 2147483647	0	Close broker connections after the specified time of inactivity. Disable with 0. If this property is left at its default value some heuristics are performed to determine a suitable default value, this is currently limited to identifying brokers on Azure (see librdkafka issue #3109 for more info).
message_max_bytes	*	1000 .. 1000000000	1000000	Maximum Kafka protocol request message size. Due to differing framing overhead between protocol versions the producer is unable to reliably enforce a strict max message limit at produce time and may exceed the maximum size by one message in protocol ProduceRequests, the broker will enforce the the topic's max_message_bytes limit (see Apache Kafka documentation).
message_copy_max_bytes	*	0 .. 1000000000	65535	Maximum size for message to be copied to buffer. Messages larger than this will be passed by reference (zero-copy) at the expense of larger iovecs.
receive_message_max_bytes	*	1000 .. 2147483647	100000000	Maximum Kafka protocol response message size. This serves as a safety precaution to avoid memory exhaustion in case of protocol hickups. This value must be at least fetch_max_bytes + 512 to allow for protocol overhead; the value is adjusted automatically unless the configuration property is explicitly set.
max_in_flight	*	1 .. 1000000	1000000	Maximum number of in-flight requests per broker connection. This is a generic property applied to all broker communication, however it is primarily relevant to produce requests. In particular, note that other mechanisms limit the number of outstanding consumer fetch request per broker to one.
metadata_request_timeout_ms	*	10 .. 900000	60000	Non-topic request timeout in milliseconds. This is for metadata requests
topic_metadata_refresh_interval_ms	*	-1 .. 3600000	300000	Topic metadata refresh interval in milliseconds. The metadata is automatically refreshed on error and connect. Use -1 to disable the intervalled refresh.
metadata_max_age_ms	*	1 .. 86400000	900000	Metadata cache max age. Defaults to topic_metadata_refresh_interval_ms * 3
topic_metadata_refresh_fast_interval_ms	*	1 .. 60000	250	When a topic loses its leader a new metadata request will be enqueued with this initial interval, exponentially increasing until the topic metadata has been refreshed. This is used to recover quickly from transitioning leader brokers
topic_metadata_refresh_sparse	*	true, false	true	Sparse metadata requests (consumes less network bandwidth)
topic_metadata_propagation_max_ms	*	0 .. 3600000	30000	Apache Kafka topic creation is asynchronous and it takes some time for a new topic to propagate throughout the cluster to all brokers. If a client requests topic metadata after manual topic creation but before the topic has been fully propagated to the broker the client is requesting metadata from, the topic will seem to be non-existent and the client will mark the topic as such, failing queued produced messages with ERR__UNKNOWN_TOPIC. This setting delays marking a topic as non-existent until the configured propagation max time has passed. The maximum propagation time is calculated from the time the topic is first referenced in the client.
topic_blacklist	*			Topic blacklist, a comma-separated list of regular expressions for matching topic names that should be ignored in broker metadata information as if the topics did not exist
debug	*	generic, broker, topic, metadata, feature, queue, msg, protocol, cgrp, security, fetch, interceptor, plugin, consumer, admin, eos, mock, assignor, conf, all
socket_timeout_ms	*	10 .. 300000	60000	Timeout for network requests
socket_send_buffer_bytes	*	0 .. 100000000	0	Broker socket send buffer size. System default is used if 0
socket_receive_buffer_bytes	*	0 .. 100000000	0	Broker socket receive buffer size. System default is used if 0
socket_keepalive_enable	*	true, false	false	Enable TCP keep-alives (SO_KEEPALIVE) on broker sockets
socket_nagle_disable	*	true, false	false	Disable the Nagle algorithm on broker sockets (TCP_NODELAY)
socket_max_fails	*	0 .. 1000000	1	Disconnect from broker when this number of send failures (e.g., timed out requests) is reached. Disable with 0. NOTE: The connection is automatically re-established
broker_address_ttl	*	0 .. 86400000	1000	How long to cache the broker address resolving results (milliseconds)
broker_address_family	*	any, v4, v6	any	Allowed broker IP address families: any, v4, v6
reconnect_backoff_ms	*	0 .. 3600000	100	The initial time to wait before reconnecting to a broker after the connection has been closed. The time is increased exponentially until reconnect.backoff.max.ms is reached. -25% to +50% jitter is applied to each reconnect backoff. A value of 0 disables the backoff and reconnects immediately.
reconnect_backoff_max_ms	*	0 .. 3600000	10000	The maximum time to wait before reconnecting to a broker after the connection has been closed.
statistics_interval_ms	*	0 .. 86400000	0	Statistics emit interval. The application also needs to register a stats callback using stats_callback config. The granularity is 1000ms. A value of 0 disables statistics.
enabled_events	*	0 .. 2147483647	0	Enable event sourcing. A bitmask of events to enable for consuming.
stats_callback	*	module or fun/2	undefined	A callback where stats are sent
log_level	*	0 .. 7	6	Logging level (syslog(3) levels)
log_queue	*	true, false	false	Disable spontaneous log_cb from internal librdkafka threads, instead enqueue log messages on queue set with rd_kafka_set_log_queue() and serve log callbacks or events through the standard poll APIs. NOTE: Log messages will linger in a temporary queue until the log queue has been set.
log_thread_name	*	true, false	true	Print internal thread name in log messages (useful for debugging librdkafka internals).
enable_random_seed	*	true, false	true	If enabled librdkafka will initialize the PRNG with srand(current_time.milliseconds) on the first invocation of rd_kafka_new() (required only if rand_r() is not available on your platform). If disabled the application must call srand() prior to calling rd_kafka_new().
log_connection_close	*	true, false	true	Log broker disconnects. It might be useful to turn this off when interacting with 0.9 brokers with an aggressive connection_max_idle_ms value.
api_version_request	*	true, false	true	Request broker's supported API versions to adjust functionality to available protocol features. If set to false, or the ApiVersionRequest fails, the fallback version broker_version_fallback will be used. NOTE: Depends on broker version >=0.10.0. If the request is not supported by (an older) broker the broker_version_fallback fallback is used
api_version_request_timeout_ms	*	1 .. 300000	10000	Timeout for broker API version requests.
api_version_fallback_ms	*	0 .. 604800000	0	Dictates how long the broker_version_fallback fallback is used in the case the ApiVersionRequest fails. NOTE: The ApiVersionRequest is only issued when a new connection to the broker is made (such as after an upgrade)
broker_version_fallback	*		0.10.0	Older broker versions (<0.10.0) provides no way for a client to query for supported protocol features (ApiVersionRequest, see api_version_request) making it impossible for the client to know what features it may use. As a workaround a user may set this property to the expected broker version and the client will automatically adjust its feature set accordingly if the ApiVersionRequest fails (or is disabled). The fallback broker version will be used for api_version_fallback_ms. Valid values are: 0.9.0, 0.8.2, 0.8.1, 0.8.0.
security_protocol	*	plaintext, ssl, sasl_plaintext, sasl_ssl	plaintext	Protocol used to communicate with brokers
ssl_cipher_suites	*			A cipher suite is a named combination of authentication, encryption, MAC and key exchange algorithm used to negotiate the security settings for a network connection using TLS or SSL network protocol. See manual page for ciphers(1) and `SSL_CTX_set_cipher_list(3)
ssl_curves_list	*			The supported-curves extension in the TLS ClientHello message specifies the curves (standard/named, or 'explicit' GF(2^k) or GF(p)) the client is willing to have the server use. See manual page for SSL_CTX_set1_curves_list(3). OpenSSL >= 1.0.2 required.
ssl_sigalgs_list	*			The client uses the TLS ClientHello signature_algorithms extension to indicate to the server which signature/hash algorithm pairs may be used in digital signatures. See manual page for SSL_CTX_set1_sigalgs_list(3). OpenSSL >= 1.0.2 required.
ssl_key_location	*			Path to client's private key (PEM) used for authentication.
ssl_key_password	*			Private key passphrase
ssl_key_pem	*			Client's private key string (PEM format) used for authentication.
ssl_certificate_location	*			Path to client's public key (PEM) used for authentication.
ssl_certificate_pem	*			Client's public key string (PEM format) used for authentication.
ssl_ca_location	*			File or directory path to CA certificate(s) for verifying the broker's key.
ssl_crl_location	*			Path to CRL for verifying broker's certificate validity.
ssl_keystore_location	*			Path to client's keystore (PKCS#12) used for authentication.
ssl_keystore_password	*			Client's keystore (PKCS#12) password.
enable_ssl_certificate_verification	*	true, false	true	Enable OpenSSL's builtin broker (server) certificate verification.
ssl_endpoint_identification_algorithm	*	none, https	none	Endpoint identification algorithm to validate broker hostname using broker certificate. https - Server (broker) hostname verification as specified in RFC2818. none - No endpoint verification. OpenSSL >= 1.0.2 required.
sasl_mechanisms	*		GSSAPI	SASL mechanism to use for authentication. Supported: GSSAPI, PLAIN, SCRAM-SHA-256, SCRAM-SHA-512. NOTE: Despite the name only one mechanism must be configured.
sasl_kerberos_service_name	*		kafka	Kerberos principal name that Kafka runs as
sasl_kerberos_principal	*		kafkaclient	This client's Kerberos principal name.
sasl_kerberos_kinit_cmd	*			Full kerberos kinit command string, %{config.prop.name} is replaced by corresponding config object value, %{broker.name} returns the broker's hostname
sasl_kerberos_keytab	*			Path to Kerberos keytab file. Uses system default if not set.NOTE: This is not automatically used but must be added to the template in sasl_kerberos_kinit_cmd as ... -t %{sasl_kerberos_keytab}
sasl_kerberos_min_time_before_relogin	*	0 .. 86400000	60000	Minimum time in milliseconds between key refresh attempts.
sasl_username	*			SASL username for use with the PLAIN and SASL-SCRAM-.. mechanisms
sasl_password	*			SASL password for use with the PLAIN and SASL-SCRAM-.. mechanism
sasl_oauthbearer_config	*			SASL/OAUTHBEARER configuration. The format is implementation-dependent and must be parsed accordingly. The default unsecured token implementation (see https://tools.ietf.org/html/rfc7515#appendix-A.5) recognizes space-separated name=value pairs with valid names including principalClaimName, principal, scopeClaimName, scope, and lifeSeconds. The default value for principalClaimName is "sub", the default value for scopeClaimName is "scope", and the default value for lifeSeconds is 3600. The scope value is CSV format with the default value being no/empty scope. For example: principalClaimName=azp principal=admin scopeClaimName=roles scope=role1,role2 lifeSeconds=600. In addition, SASL extensions can be communicated to the broker via extension_NAME=value. For example: principal=admin extension_traceId=123.
enable_sasl_oauthbearer_unsecure_jwt	*	true, false	false	Enable the builtin unsecure JWT OAUTHBEARER token handler if no oauthbearer_refresh_cb has been set. This builtin handler should only be used for development or testing, and not in production.
oauthbearer_token_refresh_callback	*	module or fun/2	undefined	A callback to implement SASL/OAUTHBEARER token refresh.
sasl_oauthbearer_method	*	default, oidc	default	Set to "default" or "oidc" to control which login method to be used. If set to "oidc", the following properties must also be be specified: sasl_oauthbearer_client_id, sasl_oauthbearer_client_secret, and sasl_oauthbearer_token_endpoint_url.
sasl_oauthbearer_client_id	*			Public identifier for the application. Must be unique across all clients that the authorization server handles. Only used when sasl_oauthbearer_method is set to "oidc".
sasl_oauthbearer_client_secret	*			Client secret only known to the application and the authorization server. This should be a sufficiently random string that is not guessable. Only used when sasl_oauthbearer_method is set to "oidc".
sasl_oauthbearer_scope	*			Client use this to specify the scope of the access request to the broker. Only used when sasl_oauthbearer_method is set to "oidc".
sasl.oauthbearer.extensions	*			Allow additional information to be provided to the broker. Comma-separated list of key=value pairs. E.g., "supportFeatureX=true,organizationId=sales-emea".Only used when sasl_oauthbearer_method is set to "oidc".
sasl_oauthbearer_token_endpoint_url	*			OAuth/OIDC issuer token endpoint HTTP(S) URI used to retrieve token. Only used when sasl_oauthbearer_method is set to "oidc".
plugin_library_paths	*		undefined	Path where librdkafka plugins are located
group_instance_id	C			Enable static group membership. Static group members are able to leave and rejoin a group within the configured session.timeout.ms without prompting a group rebalance. This should be used in combination with a larger session.timeout.ms to avoid group rebalances caused by transient unavailability (e.g. process restarts). Requires broker version >= 2.3.0.
partition_assignment_strategy	C		range, roundrobin	Name of partition assignment strategy to use when elected group leader assigns partitions to group members
session_timeout_ms	C	1 .. 3600000	10000	Client group session and failure detection timeout
heartbeat_interval_ms	C	1 .. 3600000	3000	Group session keepalive heartbeat interval
group_protocol_type	C		consumer	Group protocol type. NOTE: Currently, the only supported group protocol type is consumer.
coordinator_query_interval_ms	C	1 .. 3600000	600000	How often to query for the current client group coordinator. If the currently assigned coordinator is down the configured query interval will be divided by ten to more quickly recover in case of coordinator reassignment
max_poll_interval_ms	C	1 .. 86400000	300000	Maximum allowed time between calls to consume messages (e.g., rd_kafka_consumer_poll()) for high-level consumers. If this interval is exceeded the consumer is considered failed and the group will rebalance in order to reassign the partitions to another consumer group member. Warning: Offset commits may be not possible at this point. The interval is checked two times per second. See KIP-62 for more information.
auto_commit_interval_ms	C	0 .. 86400000	5000	The frequency in milliseconds that the consumer offsets are committed (written) to offset storage. (0 = disable). This setting is used by the high-level consumer
queued_min_messages	C	1 .. 10000000	100000	Minimum number of messages per topic+partition in the local consumer queue
queued_max_messages_kbytes	C	1 .. 1000000000	65536	Maximum number of kilobytes per topic+partition in the local consumer queue. This value may be overshot by fetch_message_max_bytes
fetch_wait_max_ms	C	0 .. 300000	500	Maximum time the broker may wait to fill the response with fetch_min_bytes
fetch_message_max_bytes	C	1 .. 1000000000	1048576	Initial maximum number of bytes per topic+partition to request when fetching messages from the broker. If the client encounters a message larger than this value it will gradually try to increase it until the entire message can be fetched
fetch_max_bytes	C	0 .. 2147483135	52428800	Maximum amount of data the broker shall return for a Fetch request. Messages are fetched in batches by the consumer and if the first message batch in the first non-empty partition of the Fetch request is larger than this value, then the message batch will still be returned to ensure the consumer can make progress. The maximum message batch size accepted by the broker is defined via message_max_bytes (broker config) or max_message_bytes (broker topic config). fetch_max_bytes is automatically adjusted upwards to be at least message_max_bytes (consumer config).
fetch_min_bytes	C	1 .. 100000000	1	Minimum number of bytes the broker responds with. If fetch.wait.max.ms expires the accumulated data will be sent to the client regardless of this setting
fetch_error_backoff_ms	C	0 .. 300000	500	How long to postpone the next fetch request for a topic+partition in case of a fetch error
isolation_level	C	read_uncommitted, read_committed	read_committed	Controls how to read messages written transactionally: read_committed - only return transactional messages which have been committed. read_uncommitted - return all messages, even transactional messages which have been aborted.
check_crcs	C	true, false	false	Verify CRC32 of consumed messages, ensuring no on-the-wire or on-disk corruption to the messages occurred. This check comes at slightly increased CPU usage
allow_auto_create_topics	C	true, false	true	Allow automatic topic creation on the broker when subscribing to or assigning non-existent topics. The broker must also be configured with auto.create.topics.enable=true for this configuration to take effect. Requires broker version >= 0.11.0.0, for older broker versions only the broker configuration applies.
client_rack	*			A rack identifier for this client. This can be any string value which indicates where this client is physically located. It corresponds with the broker config broker.rack.
transactional_id	P			Enables the transactional producer. The transactional.id is used to identify the same transactional producer instance across process restarts. It allows the producer to guarantee that transactions corresponding to earlier instances of the same producer have been finalized prior to starting any new transactions, and that any zombie instances are fenced off. If no transactional.id is provided, then the producer is limited to idempotent delivery (if enable.idempotence is set). Requires broker version >= 0.11.0.
transaction.timeout.ms	P	1000 .. 2147483647	60000	The maximum amount of time in milliseconds that the transaction coordinator will wait for a transaction status update from the producer before proactively aborting the ongoing transaction. If this value is larger than the transaction.max.timeout.ms setting in the broker, the init_transactions() call will fail with ERR_INVALID_TRANSACTION_TIMEOUT. The transaction timeout automatically adjusts message.timeout.ms and socket.timeout.ms, unless explicitly configured in which case they must not exceed the transaction timeout (socket.timeout.ms must be at least 100ms lower than transaction.timeout.ms). This is also the default timeout value if no timeout (-1) is supplied to the transactional API methods.
enable_idempotence	P	true, false	false	When set to true, the producer will ensure that messages are successfully produced exactly once and in the original produce order. The following configuration properties are adjusted automatically (if not modified by the user) when idempotence is enabled: max_in_flight_requests_per_connection=5 (must be less than or equal to 5), retries=INT32_MAX (must be greater than 0), acks=all, queuing_strategy=fifo. Producer instantation will fail if user-supplied configuration is incompatible.
enable_gapless_guarantee	P	true, false	false	When set to true, any error that could result in a gap in the produced message series when a batch of messages fails, will raise a fatal error (ERR__GAPLESS_GUARANTEE) and stop the producer. Requires enable_idempotence=true.
queue_buffering_max_messages	P	1 .. 10000000	100000	Maximum number of messages allowed on the producer queue. This queue is shared by all topics and partitions.
queue_buffering_max_kbytes	P	1 .. 2147483647	1048576	Maximum total message size sum allowed on the producer queue. This queue is shared by all topics and partitions. This property has higher priority than queue_buffering_max_messages.
queue_buffering_max_ms	P	0 .. 900000	5	Maximum time, in milliseconds, for buffering data on the producer queue
message_send_max_retries	P	0 .. 2147483647	2147483647	How many times to retry sending a failing MessageSet. Note: retrying may cause reordering
retry_backoff_ms	P	1 .. 300000	100	The backoff time in milliseconds before retrying a message send
queue_buffering_backpressure_threshold	P	1 .. 1000000	1	The threshold of outstanding not yet transmitted broker requests needed to backpressure the producer's message accumulator. If the number of not yet transmitted requests equals or exceeds this number, produce request creation that would have otherwise been triggered (for example, in accordance with linger.ms) will be delayed. A lower number yields larger and more effective batches. A higher value can improve latency when using compression on slow machines.
queue_buffering_overflow_strategy	P	local_disk_queue, block_calling_process, drop_records	local_disk_queue	What strategy to pick in case the memory queue is full: write messages on a local disk queue and send them in kafka when the in memory queue have enough space, block calling process until memory queue has enough space or drop the messages
compression_codec	P	none, gzip, snappy, lz4, zstd	none	compression codec to use for compressing message sets. This is the default value for all topics, may be overriden by the topic configuration property compression_codec
batch_num_messages	P	1 .. 1000000	10000	Maximum number of messages batched in one MessageSet. The total MessageSet size is also limited by message_max_bytes
batch_size	P	1 .. 2147483647	1000000	Maximum size (in bytes) of all messages batched in one MessageSet, including protocol framing overhead. This limit is applied after the first message has been added to the batch, regardless of the first message's size, this is to ensure that messages that exceed batch.size are produced. The total MessageSet size is also limited by batch_num_messages and message_max_bytes.
delivery_report_only_error	P	true, false	false	Only provide delivery reports for failed messages
delivery_report_callback	P	module or fun/2	undefined	A callback where delivery reports are sent (erlkaf_producer_callbacks behaviour)
sticky_partitioning_linger_ms	P	0 .. 900000	10	Delay in milliseconds to wait to assign new sticky partitions for each topic. By default, set to double the time of linger.ms. To disable sticky behavior, set to 0. This behavior affects messages with the key NULL in all cases, and messages with key lengths of zero when the consistent_random partitioner is in use. These messages would otherwise be assigned randomly. A higher value allows for more effective batching of these messages.

Topic configuration properties

C/P legend: C = Consumer, P = Producer, * = both

Property	C/P	Range	Default	Description
request_required_acks	P	-1 .. 1000	-1	This field indicates how many acknowledgements the leader broker must receive from ISR brokers before responding to the request: 0=Broker does not send any response/ack to client, 1=Only the leader broker will need to ack the message, -1 or all=broker will block until message is committed by all in sync replicas (ISRs) or broker's in.sync.replicas setting before sending response.
request_timeout_ms	P	1 .. 2147483647	30000	The ack timeout of the producer request in milliseconds. This value is only enforced by the broker and relies on request_required_acks being != 0
message_timeout_ms	P	0 .. 2147483647	0	Local message timeout. This value is only enforced locally and limits the time a produced message waits for successful delivery. A time of 0 is infinite
partitioner	P	random,consistent,consistent_random, murmur2, murmur2_random	consistent_random	Partitioner: random - random distribution, consistent - CRC32 hash of key (Empty and NULL keys are mapped to single partition), consistent_random - CRC32 hash of key (Empty and NULL keys are randomly partitioned), murmur2 - Java Producer compatible Murmur2 hash of key (NULL keys are mapped to single partition), murmur2_random - Java Producer compatible Murmur2 hash of key (NULL keys are randomly partitioned. This is functionally equivalent to the default partitioner in the Java Producer.).
compression_codec	P	none, gzip, snappy, lz4, inherit, zstd	inherit	Compression codec to use for compressing message sets
compression_level	P	-1 .. 12	-1	Compression level parameter for algorithm selected by configuration property compression_codec. Higher values will result in better compression at the cost of more CPU usage. Usable range is algorithm-dependent: [0-9] for gzip; [0-12] for lz4; only 0 for snappy; -1 = codec-dependent default compression level.
auto_commit_interval_ms	C	10 .. 86400000	60000	The frequency in milliseconds that the consumer offsets are committed (written) to offset storage. This setting is used by the low-level legacy consumer
auto_offset_reset	C	smallest, earliest, beginning, largest, latest, end, error	largest	Action to take when there is no initial offset in offset store or the desired offset is out of range: 'smallest','earliest' - automatically reset the offset to the smallest offset, 'largest','latest' - automatically reset the offset to the largest offset, 'error' - trigger an error.
offset_store_path	C		.	Path to local file for storing offsets. If the path is a directory a filename will be automatically generated in that directory based on the topic and partition
offset_store_sync_interval_ms	C	-1 .. 86400000	-1	fsync() interval for the offset file, in milliseconds. Use -1 to disable syncing, and 0 for immediate sync after each write
consume_callback_max_messages	C	0 .. 1000000	0	Maximum number of messages to dispatch in one rd_kafka_consume_callback*() call (0 = unlimited).
dispatch_mode	C	one_by_one, {batch, integer()}	one_by_one	This field indicates how messages are dispatched to the message handler. One message per callback call (default) or multiple messages up to the specified size (batch). If the batch approach is used the consumer will mark as processed the last offset form the batch.
poll_idle_ms	C	0 .. 86400000	1000	This field specifies the idle time (in milliseconds) that the consumer will wait to schedule a new poll after an empty poll.