Лог-сегменты

Каждый раз, когда producer отправляет сообщение в Kafka, оно не просто «кладётся в очередь» — оно записывается на диск брокера в строго определённую физическую структуру. Понимание этой структуры критически важно для правильного конфигурирования Kafka, диагностики проблем с производительностью и объяснения гарантий, которые даёт платформа.

Партиция как директория на диске

Каждая партиция топика — это директория на файловой системе брокера. Если у вас топик orders с тремя партициями, на диске брокера вы увидите три директории:

/kafka-logs/
  orders-0/
  orders-1/
  orders-2/

Если топик реплицирован, каждый брокер, хранящий реплику партиции, будет иметь соответствующую директорию у себя. Брокер-лидер и фолловеры хранят одинаковую структуру файлов.

Внутри директории партиции находятся лог-сегменты — группы файлов, которые хранят данные определённого диапазона офсетов.

Три типа файлов сегмента

Каждый сегмент состоит из трёх файлов с одинаковым базовым именем (base offset) и разными расширениями:

Анатомия лог-сегмента

Лог-сегменты: .log / .index / .timeindex

Директория партиции: /kafka-logs/topic-events-0/

Сегмент 1 (base=0)

.log файлoffsets 0–999

.index файлsparse index

.timeindex файлtimestamp→offset

Сегмент 2 (base=1000)

.log файлoffsets 1000–1999

.index файлsparse index

.timeindex файлtimestamp→offset

АКТИВНЫЙ сегмент (base=2000)

.log файлoffsets 2000–...

.index файлрастёт

.timeindex файлрастёт

HW = offset 2087

LEO = offset 2095

Retention: удаление закрытых сегментов

Compaction: cleanup.policy=compact

.log — данные сообщений

Файл .log содержит сами сообщения в формате записей (records). Записи добавляются последовательно в конец файла (append-only). Каждая запись содержит:

Размер batch (4 байта)
CRC32 контрольную сумму
Magic byte (версия формата)
Атрибуты (compression codec, timestamp type)
Timestamp
Offset delta (смещение относительно base offset batch)
Key length + key bytes
Value length + value bytes
Headers

Записи в .log файле читаются последовательно — это намеренное архитектурное решение. Последовательные чтения с диска работают в десятки раз быстрее случайных, что позволяет Kafka обслуживать миллионы сообщений в секунду на обычных жёстких дисках.

.index — индекс смещений

Файл .index содержит разреженное (sparse) отображение: offset → позиция в байтах в .log файле.

offset=0    → byte_position=0
offset=100  → byte_position=4321
offset=200  → byte_position=8750
...

NOTE

Индекс разреженный специально. Kafka не записывает позицию каждого офсета — только каждого N-го. Параметр log.index.interval.bytes (по умолчанию 4096) контролирует, через сколько байт данных добавляется новая запись в индекс. Это баланс между размером индекса и скоростью поиска.

Когда consumer запрашивает данные начиная с offset X, Kafka выполняет бинарный поиск по .index файлу, находит ближайший меньший индексированный offset, а затем читает .log файл последовательно с найденной позиции.

.timeindex — индекс по времени

Файл .timeindex содержит отображение: timestamp → offset. Используется при запросе данных по времени (операция seekToBeginningByTime):

timestamp=1712000000000 → offset=0
timestamp=1712003600000 → offset=5000
timestamp=1712007200000 → offset=12000

Это позволяет Kafka найти ответ на вопрос: «Где в логе находится первое сообщение, чей timestamp не меньше заданного значения?» Применяется при операции --reset-offsets --to-datetime в инструментах командной строки.

Именование сегментов

Каждый сегмент называется по базовому офсету первой записи, которую он содержит:

orders-0/
  00000000000000000000.log       ← сегмент с offset 0..N
  00000000000000000000.index
  00000000000000000000.timeindex
  00000000000000005000.log       ← сегмент с offset 5000..M
  00000000000000005000.index
  00000000000000005000.timeindex
  00000000000000012000.log       ← активный сегмент (пишется прямо сейчас)
  00000000000000012000.index
  00000000000000012000.timeindex

Имена файлов — это 20-значные числа с ведущими нулями, представляющие base offset сегмента.

Активный сегмент

В каждой партиции всегда есть ровно один активный сегмент (active segment) — тот, в который в данный момент записываются новые сообщения. Его .log файл открыт для записи. Все остальные сегменты закрытые (passive/closed) — они доступны только для чтения.

Активный и закрытые сегменты

Сегмент 0 (закрытый)

Сегмент 5000 (закрытый)

Сегмент 12000 (активный)

время / офсет

Роллинг сегмента

Kafka закрывает активный сегмент и создаёт новый (roll) при выполнении одного из условий:

Параметр	Значение по умолчанию	Описание
`log.segment.bytes`	1 ГБ (1073741824)	Максимальный размер `.log` файла
`log.roll.ms`	168 часов (7 дней)	Максимальное время жизни активного сегмента
`log.roll.hours`	168	Альтернативный способ задать `log.roll.ms`
`log.index.size.max.bytes`	10 МБ	Максимальный размер `.index` файла

Когда .log файл достигает log.segment.bytes, активный сегмент закрывается и создаётся новый. Новый сегмент именуется текущим LEO (Log End Offset) партиции.

TIP

Уменьшение log.segment.bytes увеличивает количество файлов и может замедлить поиск по времени (больше сегментов для проверки). Увеличение замедляет инициализацию брокера. Значение 512 МБ — разумный компромисс для топиков с высоким throughput.

Retention: удаление старых сегментов

Kafka не удаляет отдельные записи из сегмента — она удаляет целые сегменты. Удаление применяется только к закрытым сегментам. Активный сегмент никогда не удаляется.

Политики retention:

Параметр	Описание
`log.retention.hours`	Удалять сегменты старше N часов (по умолчанию 168 = 7 дней)
`log.retention.bytes`	Удалять сегменты, если суммарный размер превышает N байт
`log.retention.ms`	Альтернатива `log.retention.hours` (миллисекунды)

Когда применяется log.retention.bytes, Kafka начинает удалять самые старые сегменты, пока суммарный размер данных партиции не опустится ниже лимита.

WARNING

Гранулярность удаления — это целый сегмент, а не отдельные сообщения. Если сегмент содержит сообщение, которому только что исполнилось retention.hours, но он содержит также более свежие сообщения — сегмент не удаляется, пока все его сообщения не устареют. Поэтому фактическое время хранения может быть до retention + segment.bytes/throughput дольше указанного.

leader-epoch-checkpoint

В директории партиции также хранится файл leader-epoch-checkpoint. Он записывает историю смены эпох лидера:

2
0 0
1 5000

Каждая строка — это (epoch, startOffset). Этот файл используется при восстановлении реплики: фолловер сравнивает свою историю эпох с лидером и определяет, нужно ли выполнить truncation для восстановления консистентности.

Проверка знанийKnowledge check

Почему .index файл в Kafka разреженный (sparse), а не содержит позицию каждого офсета?

ОтветAnswer

Хранение позиции каждого офсета потребовало бы памяти O(N), где N — число сообщений. Для миллиардов сообщений это сотни гигабайт только для индексов. Разреженный индекс: (1) хранится компактно — каждые 4096 байт данных одна запись; (2) полностью помещается в RAM брокера; (3) бинарный поиск находит ближайший индексированный offset за O(log N), после чего линейное чтение .log файла добирает нужный offset. Потеря в скорости поиска минимальна, выигрыш в памяти — многократный.