// This module is included in the following files:
//
// assembly-client-config.adoc

[id='con-broker-config-properties-{context}']
= Kafka broker configuration tuning

[role="_abstract"]
Use configuration properties to optimize the performance of Kafka brokers.
You can use standard Kafka broker configuration options, except for properties managed directly by Strimzi.

== Basic broker configuration
A typical broker configuration will include settings for properties related to topics, threads and logs.

.Basic broker configuration properties
[source,env]
----
# ...
num.partitions=1
default.replication.factor=3
offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2
log.retention.hours=168
log.segment.bytes=1073741824
log.retention.check.interval.ms=300000
num.network.threads=3
num.io.threads=8
num.recovery.threads.per.data.dir=1
socket.send.buffer.bytes=102400
socket.receive.buffer.bytes=102400
socket.request.max.bytes=104857600
group.initial.rebalance.delay.ms=0
# ...
----

== Replicating topics for high availability

Basic topic properties set the default number of partitions and replication factor for topics, which will apply to topics that are created without these properties being explicitly set, including when topics are created automatically.

[source,env]
----
# ...
num.partitions=1
auto.create.topics.enable=false
default.replication.factor=3
min.insync.replicas=2
replica.fetch.max.bytes=1048576
# ...
----

For high availability environments, it is advisable to increase the replication factor to at least 3 for topics and set the minimum number of in-sync replicas required to 1 less than the replication factor.

The `auto.create.topics.enable` property is enabled by default so that topics that do not already exist are created automatically when needed by producers and consumers.
If you are using automatic topic creation, you can set the default number of partitions for topics using `num.partitions`.
Generally, however, this property is disabled so that more control is provided over topics through explicit topic creation.

For xref:data_durability[data durability], you should also set `min.insync.replicas` in your _topic_ configuration and message delivery acknowledgments using `acks=all` in your _producer_ configuration.

Use `replica.fetch.max.bytes` to set the maximum size, in bytes, of messages fetched by each follower that replicates the leader partition.
Change this value according to the average message size and throughput. When considering the total memory allocation required for read/write buffering, the memory available must also be able to accommodate the maximum replicated message size when multiplied by all followers.

The `delete.topic.enable` property is enabled by default to allow topics to be deleted.
In a production environment, you should disable this property to avoid accidental topic deletion, resulting in data loss.
You can, however, temporarily enable it and delete topics and then disable it again.

NOTE: When running Strimzi on Kubernetes, the Topic Operator can provide operator-style topic management. You can use the `KafkaTopic` resource to create topics.
For topics created using the `KafkaTopic` resource, the replication factor is set using `spec.replicas`.
If `delete.topic.enable` is enabled, you can also delete topics using the `KafkaTopic` resource.

[source,env]
----
# ...
auto.create.topics.enable=false
delete.topic.enable=true
# ...
----

== Internal topic settings for transactions and commits

If you are xref:reliability_guarantees[using transactions] to enable atomic writes to partitions from producers, the state of the transactions is stored in the internal `__transaction_state` topic.
By default, the brokers are configured with a replication factor of 3 and a minimum of 2 in-sync replicas for this topic, which means that a minimum of three brokers are required in your Kafka cluster.

[source,env]
----
# ...
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2
# ...
----

Similarly, the internal `__consumer_offsets` topic, which stores consumer state, has default settings for the number of partitions and replication factor.

[source,env]
----
# ...
offsets.topic.num.partitions=50
offsets.topic.replication.factor=3
# ...
----

*Do not reduce these settings in production.*
You can increase the settings in a _production_ environment.
As an exception, you might want to reduce the settings in a single-broker _test_ environment.

== Improving request handling throughput by increasing I/O threads

Network threads handle requests to the Kafka cluster, such as produce and fetch requests from client applications.
Produce requests are placed in a request queue. Responses are placed in a response queue.

The number of network threads per listener should reflect the replication factor and the levels of activity from client producers and consumers interacting with the Kafka cluster.
If you are going to have a lot of requests, you can increase the number of threads, using the amount of time threads are idle to determine when to add more threads.

To reduce congestion and regulate the request traffic, you can limit the number of requests allowed in the request queue.
When the request queue is full, all incoming traffic is blocked.

I/O threads pick up requests from the request queue to process them.
Adding more threads can improve throughput, but the number of CPU cores and disk bandwidth imposes a practical upper limit.
At a minimum, the number of I/O threads should equal the number of storage volumes.

[source,env]
----
# ...
num.network.threads=3 <1>
queued.max.requests=500 <2>
num.io.threads=8 <3>
num.recovery.threads.per.data.dir=4 <4>
# ...
----
<1> The number of network threads for the Kafka cluster.
<2> The number of requests allowed in the request queue.
<3> The number of I/O  threads for a Kafka broker.
<4> The number of threads used for log loading at startup and flushing at shutdown. Try setting to a value of at least the number of cores.

Configuration updates to the thread pools for all brokers might occur dynamically at the cluster level.
These updates are restricted to between half the current size and twice the current size.

[TIP]
====
The following Kafka broker metrics can help with working out the number of threads required:

* `kafka.network:type=SocketServer,name=NetworkProcessorAvgIdlePercent` provides metrics on the average time network threads are idle as a percentage.
* `kafka.server:type=KafkaRequestHandlerPool,name=RequestHandlerAvgIdlePercent` provides metrics on the average time I/O threads are idle as a percentage.

If there is 0% idle time, all resources are in use, which means that adding more threads might be beneficial.
When idle time goes below 30%, performance may start to suffer.
====

If threads are slow or limited due to the number of disks, you can try increasing the size of the buffers for network requests to improve throughput:

[source,env]
----
# ...
replica.socket.receive.buffer.bytes=65536
# ...
----

And also increase the maximum number of bytes Kafka can receive:

[source,env]
----
# ...
socket.request.max.bytes=104857600
# ...
----

== Increasing bandwidth for high latency connections

Kafka batches data to achieve reasonable throughput over high-latency connections from Kafka to clients, such as connections between datacenters.
However, if high latency is a problem, you can increase the size of the buffers for sending and receiving messages.

[source,env]
----
# ...
socket.send.buffer.bytes=1048576
socket.receive.buffer.bytes=1048576
# ...
----

You can estimate the optimal size of your buffers using a _bandwidth-delay product_ calculation,
which multiplies the maximum bandwidth of the link (in bytes/s) with the round-trip delay (in seconds) to give an estimate of how large a buffer is required to sustain maximum throughput.

== Managing Kafka logs with delete and compact policies

Kafka relies on logs to store message data. 
A log consists of a series of segments, where each segment is associated with offset-based and timestamp-based indexes.
New messages are written to an _active_ segment and are never subsequently modified. 
When serving fetch requests from consumers, the segments are read. 
Periodically, the active segment is _rolled_ to become read-only, and a new active segment is created to replace it. 
There is only one active segment per topic-partition per broker. 
Older segments are retained until they become eligible for deletion.

Configuration at the broker level determines the maximum size in bytes of a log segment and the time in milliseconds before an active segment is rolled:

[source,env]
----
# ...
log.segment.bytes=1073741824
log.roll.ms=604800000
# ...
----

These settings can be overridden at the topic level using `segment.bytes` and `segment.ms`. 
The choice to lower or raise these values depends on the policy for segment deletion. 
A larger size means the active segment contains more messages and is rolled less often. 
Segments also become eligible for deletion less frequently.

In Kafka, log cleanup policies determine how log data is managed.
In most cases, you won't need to change the default configuration at the cluster level, which specifies the `delete` cleanup policy and enables the log cleaner used by the `compact` cleanup policy:

[source,env]
----
# ...
log.cleanup.policy=delete
log.cleaner.enable=true
# ...
----

Delete cleanup policy:: Delete cleanup policy is the default cluster-wide policy for all topics.
The policy is applied to topics that do not have a specific topic-level policy configured. 
Kafka removes older segments based on time-based or size-based log retention limits. 
Compact cleanup policy:: Compact cleanup policy is generally configured as a topic-level policy (`cleanup.policy=compact`).
Kafka's log cleaner applies compaction on specific topics, retaining only the most recent value for a key in the topic.
You can also configure topics to use both policies (`cleanup.policy=compact,delete`). 

.Setting up retention limits for the delete policy

Delete cleanup policy corresponds to managing logs with data retention. 
The policy is suitable when data does not need to be retained forever.
You can establish time-based or size-based log retention and cleanup policies to keep logs bounded. 

When log retention policies are employed, non-active log segments are removed when retention limits are reached.
Deletion of old segments helps to prevent exceeding disk capacity.

For time-based log retention, you set a retention period based on hours, minutes, or milliseconds: 

[source,env]
----
# ...
log.retention.ms=1680000
# ...
----

The retention period is based on the time messages were appended to the segment. 
Kafka uses the timestamp of the latest message within a segment to determine if that segment has expired or not.
The milliseconds configuration has priority over minutes, which has priority over hours. 
The minutes and milliseconds configurations are null by default, but the three options provide a substantial level of control over the data you wish to retain. 
Preference should be given to the milliseconds configuration, as it is the only one of the three properties that is dynamically updateable.

If `log.retention.ms` is set to -1, no time limit is applied to log retention, and all logs are retained. 
However, this setting is not generally recommended as it can lead to issues with full disks that are difficult to rectify.

For size-based log retention, you specify a minimum log size (in bytes):

[source,env]
----
# ...
log.retention.bytes=1073741824
# ...
----

This means that Kafka will ensure there is always at least the specified amount of log data available.

For example, if you set `log.retention.bytes` to 1000 and `log.segment.bytes` to 300, Kafka will keep 4 segments plus the active segment, ensuring a minimum of 1000 bytes are available. 
When the active segment becomes full and a new segment is created, the oldest segment is deleted. 
At this point, the size on disk may exceed the specified 1000 bytes, potentially ranging between 1200 and 1500 bytes (excluding index files).

A potential issue with using a log size is that it does not take into account the time messages were appended to a segment.
You can use time-based and size-based log retention for your cleanup policy to get the balance you need.
Whichever threshold is reached first triggers the cleanup.

To add a time delay before a segment file is deleted from the system, you can use `log.segment.delete.delay.ms` at the broker level for all topics:

[source,env]
----
# ...
log.segment.delete.delay.ms=60000
# ...
----

Or configure `file.delete.delay.ms` at the topic level.

You set the frequency at which the log is checked for cleanup in milliseconds:

[source,env]
----
# ...
log.retention.check.interval.ms=300000
# ...
----

Adjust the log retention check interval in relation to the log retention settings. 
Smaller retention sizes might require more frequent checks. 
The frequency of cleanup should be often enough to manage the disk space but not so often it affects performance on a broker.

.Retaining the most recent messages using compact policy

When you enable log compaction for a topic by setting `cleanup.policy=compact`, Kafka uses the log cleaner as a background thread to perform the compaction.
The compact policy guarantees that the most recent message for each message key is retained, effectively cleaning up older versions of records. 
The policy is suitable when message values are changeable, and you want to retain the latest update.

If a cleanup policy is set for log compaction, the _head_ of the log operates as a standard Kafka log, with writes for new messages appended in order. 
In the _tail_ of a compacted log, where the log cleaner operates, records are deleted if another record with the same key occurs later in the log. 
Messages with null values are also deleted. 
To use compaction, you must have keys to identify related messages because Kafka guarantees that the latest messages for each key will be retained, but it does not guarantee that the whole compacted log will not contain duplicates.

.Log showing key value writes with offset positions before compaction
image::tuning/broker-tuning-compaction-before.png[Image of compaction showing key value writes]

Using keys to identify messages, Kafka compaction keeps the latest message (with the highest offset) that is present in the log tail for a specific message key, eventually discarding earlier messages that have the same key. 
The message in its latest state is always available, and any out-of-date records of that particular message are eventually removed when the log cleaner runs. 
You can restore a message back to a previous state.
Records retain their original offsets even when surrounding records get deleted. 
Consequently, the tail can have non-contiguous offsets. 
When consuming an offset that's no longer available in the tail, the record with the next higher offset is found.

.Log after compaction
image::tuning/broker-tuning-compaction-after.png[Image of compaction after log cleanup]

If appropriate, you can add a delay to the compaction process:

[source,env]
----
# ...
log.cleaner.delete.retention.ms=86400000
# ...
----
The deleted data retention period gives time to notice the data is gone before it is irretrievably deleted.

To delete all messages related to a specific key, a producer can send a _tombstone_ message. 
A tombstone has a null value and acts as a marker to inform consumers that the corresponding message for that key has been deleted. 
After some time, only the tombstone marker is retained. 
Assuming new messages continue to come in, the marker is retained for a duration specified by `log.cleaner.delete.retention.ms` to allow consumers enough time to recognize the deletion.

You can also set a time in milliseconds to put the cleaner on standby if there are no logs to clean:

[source,env]
----
# ...
log.cleaner.backoff.ms=15000
# ...
----

.Using combined compact and delete policies 

If you choose only a compact policy, your log can still become arbitrarily large. 
In such cases, you can set the cleanup policy for a topic to compact and delete logs.
Kafka applies log compaction, removing older versions of records and retaining only the latest version of each key. 
Kafka also deletes records based on the specified time-based or size-based log retention settings. 

For example, in the following diagram only the latest message (with the highest offset) for a specific message key is retained up to the compaction point.
If there are any records remaining up to the retention point they are deleted.
In this case, the compaction process would remove all duplicates. 

.Log retention point and compaction point
image::tuning/broker-tuning-compaction-retention.png[Image of compaction with retention point]


== Managing efficient disk utilization for compaction

When employing the compact policy and log cleaner to handle topic logs in Kafka, consider optimizing memory allocation.

You can fine-tune memory allocation using the deduplication property (`dedupe.buffer.size`), which determines the total memory allocated for cleanup tasks across all log cleaner threads. 
Additionally, you can establish a maximum memory usage limit by defining a percentage through the `buffer.load.factor` property.

[source,env]
----
# ...
log.cleaner.dedupe.buffer.size=134217728
log.cleaner.io.buffer.load.factor=0.9
# ...
----

Each log entry uses exactly 24 bytes, so you can work out how many log entries the buffer can handle in a single run and adjust the setting accordingly.

If possible, consider increasing the number of log cleaner threads if you are looking to reduce the log cleaning time:

[source,env]
----
# ...
log.cleaner.threads=8
# ...
----

If you are experiencing issues with 100% disk bandwidth usage, you can throttle the log cleaner I/O so that the sum of the read/write operations is less than a specified double value based on the capabilities of the disks performing the operations:

[source,env]
----
# ...
log.cleaner.io.max.bytes.per.second=1.7976931348623157E308
# ...
----

== Controlling the log flush of message data

Generally, the recommendation is to not set explicit flush thresholds and let the operating system perform background flush using its default settings.
Partition replication provides greater data durability than writes to any single disk, as a failed broker can recover from its in-sync replicas.

Log flush properties control the periodic writes of cached message data to disk.
The scheduler specifies the frequency of checks on the log cache in milliseconds:

[source,env]
----
# ...
log.flush.scheduler.interval.ms=2000
# ...
----

You can control the frequency of the flush based on the maximum amount of time that a message is kept in-memory and the maximum number of messages in the log before writing to disk:

[source,env]
----
# ...
log.flush.interval.ms=50000
log.flush.interval.messages=100000
# ...
----

The wait between flushes includes the time to make the check and the specified interval before the flush is carried out.
Increasing the frequency of flushes can affect throughput.

If you are using application flush management, setting lower flush thresholds might be appropriate if you are using faster disks.

== Partition rebalancing for availability

Partitions can be replicated across brokers for fault tolerance.
For a given partition, one broker is elected leader and handles all produce requests (writes to the log).
Partition followers on other brokers replicate the partition data of the partition leader for data reliability in the event of the leader failing.

Followers do not normally serve clients, though `rack` configuration allows a consumer to consume messages from the closest replica when a Kafka cluster spans multiple datacenters.
Followers operate only to replicate messages from the partition leader and allow recovery should the leader fail.
Recovery requires an in-sync follower. Followers stay in sync by sending fetch requests to the leader, which returns messages to the follower in order.
The follower is considered to be in sync if it has caught up with the most recently committed message on the leader.
The leader checks this by looking at the last offset requested by the follower.
An out-of-sync follower is usually not eligible as a leader should the current leader fail, unless xref:con-broker-config-properties-unclean-{context}[unclean leader election is allowed].

You can adjust the lag time before a follower is considered out of sync:

[source,env]
----
# ...
replica.lag.time.max.ms=30000
# ...
----

Lag time puts an upper limit on the time to replicate a message to all in-sync replicas and how long a producer has to wait for an acknowledgment.
If a follower fails to make a fetch request and catch up with the latest message within the specified lag time, it is removed from in-sync replicas.
You can reduce the lag time to detect failed replicas sooner, but by doing so you might increase the number of followers that fall out of sync needlessly.
The right lag time value depends on both network latency and broker disk bandwidth.

When a leader partition is no longer available, one of the in-sync replicas is chosen as the new leader.
The first broker in a partition’s list of replicas is known as the _preferred_ leader.
By default, Kafka is enabled for automatic partition leader rebalancing based on a periodic check of leader distribution.
That is, Kafka checks to see if the preferred leader is the _current_ leader.
A rebalance ensures that leaders are evenly distributed across brokers and brokers are not overloaded.

You can use Cruise Control for Strimzi to figure out replica assignments to brokers that balance load evenly across the cluster.
Its calculation takes into account the differing load experienced by leaders and followers.
A failed leader affects the balance of a Kafka cluster because the remaining brokers get the extra work of leading additional partitions.

For the assignment found by Cruise Control to actually be balanced it is necessary that partitions are lead by the preferred leader. Kafka can automatically ensure that the preferred leader is being used (where possible), changing the current leader if necessary. This ensures that the cluster remains in the balanced state found by Cruise Control.

You can control the frequency, in seconds, of the rebalance check and the maximum percentage of imbalance allowed for a broker before a rebalance is triggered.

[source,env]
----
#...
auto.leader.rebalance.enable=true
leader.imbalance.check.interval.seconds=300
leader.imbalance.per.broker.percentage=10
#...
----

The percentage leader imbalance for a broker is the ratio between the current number of partitions for which the broker is the current leader and the number of partitions for which it is the preferred leader.
You can set the percentage to zero to ensure that preferred leaders are always elected, assuming they are in sync.

If the checks for rebalances need more control, you can disable automated rebalances. You can then choose when to trigger a rebalance using the `kafka-leader-election.sh` command line tool.

NOTE: The Grafana dashboards provided with Strimzi show metrics for under-replicated partitions and partitions that do not have an active leader.

[id='con-broker-config-properties-unclean-{context}']
== Unclean leader election

Leader election to an in-sync replica is considered clean because it guarantees no loss of data. And this is what happens by default.
But what if there is no in-sync replica to take on leadership? Perhaps the ISR (in-sync replica) only contained the leader when the leader's disk died. If a minimum number of in-sync replicas is not set, and there are no followers in sync with the partition leader when its hard drive fails irrevocably, data is already lost.
Not only that, but _a new leader cannot be elected_ because there are no in-sync followers.

You can configure how Kafka handles leader failure:

[source,env]
----
# ...
unclean.leader.election.enable=false
# ...
----

Unclean leader election is disabled by default, which means that out-of-sync replicas cannot become leaders.
With clean leader election, if no other broker was in the ISR when the old leader was lost, Kafka waits until that leader is back online before messages can be written or read.
Unclean leader election means out-of-sync replicas can become leaders, but you risk losing messages.
The choice you make depends on whether your requirements favor availability or durability.

You can override the default configuration for specific topics at the topic level.
If you cannot afford the risk of data loss, then leave the default configuration.

== Avoiding unnecessary consumer group rebalances

For consumers joining a new consumer group, you can add a delay so that unnecessary rebalances to the broker are avoided:

[source,env]
----
# ...
group.initial.rebalance.delay.ms=3000
# ...
----

The delay is the amount of time that the coordinator waits for members to join. The longer the delay,
the more likely it is that all the members will join in time and avoid a rebalance.
But the delay also prevents the group from consuming until the period has ended.
