Справочник по Apache Kafka

СПРАВОЧНИК

---

Назначение

CLI, ключи конфигурации и семантика доставки Apache Kafka в табличном виде. Учебный курс: Apache Kafka — потоковая обработка, раздел микросервисов.

---

Краткое пояснение

Kafka хранит поток записей в топиках, разбитых на партиции (упорядоченный журнал). Producer append-ит записи; consumer в group читает с offset. Репликация и лидер партиции дают отказоустойчивость. Координация: KRaft (Kafka 3.3+) или ZooKeeper (legacy).

---

Быстрый старт

# KRaft single-node (Kafka 3.x+, без ZooKeeper)
docker run -d --name kafka -p 9092:9092 \
  -e KAFKA_NODE_ID=1 \
  -e KAFKA_PROCESS_ROLES=broker,controller \
  -e KAFKA_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093 \
  -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \
  -e KAFKA_CONTROLLER_QUORUM_VOTERS=1@localhost:9093 \
  apache/kafka:latest

# топик + тест
docker exec kafka /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --create --topic demo --partitions 3 --replication-factor 1

Разбор:

• Утилиты bin/kafka-*.sh (или .bat на Windows) управляют топиками и тестовой публикацией из каталога установки Kafka.
• docker run -d стартует контейнер в фоне; -p host:container пробрасывает порты AMQP и веб-UI на localhost.
• Команды Kafka создают топик с числом партиций и фактором репликации; переменные KAFKA_* настраивают single-node KRaft в Docker.

Bootstrap: localhost:9092 (или bootstrap.servers в клиенте).

---

Справочные таблицы

Содержание справочника

• Компоненты кластера
• Команды CLI (kafka-*.sh)
• Параметры топика
• Producer — ключевые настройки
• Consumer — ключевые настройки
• Broker (server.properties)
• Consumer groups и rebalancing
• Гарантии доставки
• Клиентские библиотеки
• Наблюдаемость
• Типичные anti-patterns

---

Компоненты кластера

Компонент	Роль
Broker	Хранит партиции, принимает produce/fetch
Topic	Именованный поток записей
Partition	Упорядочный лог; единица параллелизма
Replica	Копия партиции; один leader, остальные followers
Producer	Пишет в топик (выбор партиции по key или round-robin)
Consumer	Читает с offset
Consumer group	Группа consumers; одна партиция — один consumer в группе
Offset	Позиция в партиции; хранится в __consumer_offsets
Controller	Метаданные, выбор лидеров (KRaft или ZK)

---

Команды CLI (kafka-*.sh)

Путь: $KAFKA_HOME/bin/ (в Docker — /opt/kafka/bin/).

Команда	Пример	Назначение
kafka-topics.sh --create	--topic T --partitions 6 --replication-factor 3	Создать топик
kafka-topics.sh --list	--bootstrap-server localhost:9092	Список топиков
kafka-topics.sh --describe	--topic T	Партиции, ISR, leader
kafka-topics.sh --alter	--partitions 12	Увеличить число партиций
kafka-topics.sh --delete	--topic T	Удалить (если delete.topic.enable=true)
kafka-console-producer.sh	--topic T	Интерактивная отправка
kafka-console-consumer.sh	--topic T --from-beginning --group g1	Чтение в консоль
kafka-consumer-groups.sh --list		Список групп
kafka-consumer-groups.sh --describe	--group g1	Lag по партициям
kafka-consumer-groups.sh --reset-offsets	--to-earliest --execute	Сброс offset (осторожно)
kafka-configs.sh --alter	--entity-type topics --entity-name T	Динамический config топика
kafka-broker-api-versions.sh		Совместимость API
kafka-acls.sh --add	--allow-principal User:x --operation Read --topic T	ACL
kafka-mirror-maker.sh	MM2 properties	Зеркалирование между кластерами

---

Параметры топика

Параметр	Смысл
num.partitions	Партиций по умолчанию при auto-create
replication.factor	Число реплик (≤ числа брокеров)
retention.ms	Сколько хранить записи (время)
retention.bytes	Лимит размера партиции
cleanup.policy	delete или compact (log compaction по key)
min.insync.replicas	Минимум ISR для acks=all
max.message.bytes	Макс. размер записи
compression.type	producer, gzip, lz4, zstd, snappy

Партиция выбирается: hash(key) % num_partitions при заданном key; иначе sticky / round-robin.

---

Producer — ключевые настройки

Свойство	Значения	Смысл
bootstrap.servers	host:9092,...	Адреса брокеров
key.serializer / value.serializer	класс	Сериализация
acks	0, 1, all	Подтверждение: none / leader / все ISR
retries	число	Повторы при transient error
enable.idempotence	true	Идемпотентный producer (без дублей при retry)
max.in.flight.requests.per.connection	1–5	Параллельные запросы (с idempotence ≤5)
compression.type	lz4, zstd, …	Сжатие на брокере
batch.size / linger.ms		Батчинг для throughput
delivery.timeout.ms		Общий дедлайн доставки (retry + ack)
transactional.id	строка	Транзакции produce (exactly-once в связке с consumer)

---

Consumer — ключевые настройки

Свойство	Значения	Смысл
group.id	строка	Consumer group (обязательно)
auto.offset.reset	earliest, latest, none	Если offset неизвестен
enable.auto.commit	true / false	Авто-commit offset
auto.commit.interval.ms		Интервал auto-commit
max.poll.records	число	Записей за один poll()
max.poll.interval.ms		Таймаут обработки batch; превышение → исключение из группы
fetch.min.bytes		Минимум байт для ответа fetch (батчинг на broker)
fetch.max.wait.ms		Макс. ожидание набора fetch.min.bytes
fetch.max.bytes		Верхняя граница размера fetch-ответа
max.partition.fetch.bytes		Лимит байт на партицию в одном fetch
session.timeout.ms		Падение consumer → rebalance
group.instance.id		Static membership — меньше rebalance при рестарте
isolation.level	read_uncommitted / read_committed	Видимость транзакционных записей
partition.assignment.strategy	Range, CooperativeSticky, …	Стратегия назначения партиций

Ручной commit: commitSync() / commitAsync() после обработки batch.

---

Broker (server.properties)

Ключ	Смысл
broker.id	Уникальный ID узла
listeners / advertised.listeners	Слушать / адрес для клиентов
log.dirs	Каталоги данных
num.partitions	Default для новых топиков
default.replication.factor	Default RF
offsets.topic.replication.factor	RF для __consumer_offsets
transaction.state.log.replication.factor	RF для транзакций
log.retention.hours / log.retention.bytes	Хранение по умолчанию
min.insync.replicas	Минимум синхронных реплик
delete.topic.enable	Разрешить удаление топиков
auto.create.topics.enable	Автосоздание (в prod часто false)

KRaft: process.roles=broker,controller, controller.quorum.voters, node.id — вместо zookeeper.connect.

Security (prod): listeners=SASL_SSL://..., authorizer.class.name=kafka.security.authorizer.AclAuthorizer, super.users=User:admin.

---

Consumer groups и rebalancing

Событие	Поведение
Новый consumer в группе	Rebalance: перераспределение партиций
Consumer не вызывает poll() дольше max.poll.interval.ms	Исключение из группы, rebalance
Число consumers > партиций	Лишние consumers простаивают
Static membership	group.instance.id — меньше "шторма" rebalance

Lag — разница между последним offset в партиции и committed offset группы (kafka-consumer-groups.sh --describe).

---

Гарантии доставки

Уровень	Как достичь
At-most-once	acks=0, auto-commit до обработки
At-least-once	acks=all, commit после обработки, идемпотентный consumer
Exactly-once	Транзакционный producer + read_committed + идемпотентная обработка / Kafka Streams

Порядок записей гарантирован внутри одной партиции, не между партициями.

---

Клиентские библиотеки

Язык	Библиотека
Java	org.apache.kafka:kafka-clients
Python	confluent-kafka, kafka-python
C#	Confluent.Kafka
Node.js	kafkajs
Go	segmentio/kafka-go, confluent-kafka-go
Rust	rdkafka

Schema Registry (Confluent): Avro/Protobuf/JSON Schema для эволюции контрактов событий. Подробнее — Kafka, раздел Schema Registry.

---

Schema Registry и сериализаторы

Компонент	Назначение
Subject	Имя схемы, обычно <topic>-key / <topic>-value
Schema id	Числовой id версии в реестре; в начале каждого Avro-сообщения
BACKWARD / FORWARD / FULL	Политика совместимости при регистрации новой версии
KafkaAvroSerializer	Java: регистрация схемы + сериализация
schema.registry.url	URL реестра в config producer/consumer
Apicurio / AWS Glue	Альтернативные реестры

Wire format (Confluent): 0x00 + 4-byte schema id + Avro bytes.

---

Наблюдаемость

Инструмент	Метрики / задачи
JMX	Throughput, request latency, ISR shrink
Prometheus + kafka_exporter	Lag, bytes in/out
UI: AKHQ, Kafka UI, Confluent Control Center	Топики, группы, сообщения
kafka-consumer-groups.sh	Lag в CLI

Метрики для алертов (prod):

Метрика	Порог / действие
UnderReplicatedPartitions	> 0 дольше 5 мин → проверить брокер/диск/сеть
OfflinePartitionsCount	> 0 → критично, запись недоступна
Consumer lag (max по группе)	SLO команды (например, > 60 сек)
RequestHandlerAvgIdlePercent	Устойчиво низкий → CPU bottleneck
Producer record-error-rate	> 0 → retry, auth, quota
unclean.leader.election.rate	Должен быть 0 при unclean.leader.election.enable=false

---

Типичные anti-patterns

Проблема	Решение
Один key на все сообщения	Распределение по ключам (userId, orderId)
Слишком мало партиций	Масштабирование consumers ограничено числом партиций
auto.commit до обработки	Commit после успешной бизнес-логики
Огромные сообщения (>1 MB)	Chunking, object storage + ссылка в событии
Consumer group на каждый deploy без static id	Лишние rebalance; cooperative assignor
Kafka как job queue без DLQ	Отдельный топик ошибок (*.dlq), retry с backoff
JSON без схемы в multi-team prod	Avro + Schema Registry, CI-проверка совместимости

Сравнение с очередями: Справочник по RabbitMQ.

---

В подборках

Статья входит в тематические подборки и блок "С чего начать?" на главной. Соседние шаги того же маршрута:

Справочники — Справочник по RabbitMQ, Справочник по Docker, Справочник по GraphQL, Справочник по Kubernetes, Справочник по gRPC, Справочник по Roblox.

---