Consumer Group на Go: партиции, offset commit
Consumer Group на Go: партиции, offset commit
Consumer Group - механизм горизонтального масштабирования в Kafka. Несколько воркеров объединяются под одним group.id, Kafka распределяет партиции между ними. Добавляешь воркер - автоматически забирает часть партиций. Убираешь - его партиции переходят к оставшимся (rebalance).
Базовый consumer loop
package main
import (
"context"
"log"
"os/signal"
"syscall"
"github.com/twmb/franz-go/pkg/kgo"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
client, err := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
kgo.ConsumerGroup("analytics"),
kgo.ConsumeTopics("lesson-events"),
)
if err != nil {
log.Fatal(err)
}
defer client.Close()
for {
fetches := client.PollFetches(ctx)
if fetches.IsClientClosed() || ctx.Err() != nil {
return
}
// Ошибки относятся к отдельным партициям. Записи других партиций
// из этого же poll выбрасывать нельзя: клиент уже продвинул позицию
// чтения и повторно их не отдаст. Логируем и обрабатываем остальное.
for _, e := range fetches.Errors() {
log.Printf("fetch error: topic=%s partition=%d err=%v", e.Topic, e.Partition, e.Err)
}
fetches.EachRecord(func(record *kgo.Record) {
handleEvent(record)
})
}
}
func handleEvent(r *kgo.Record) {
log.Printf("partition=%d offset=%d key=%s value=%s",
r.Partition, r.Offset, r.Key, r.Value)
// бизнес-логика
}
По умолчанию franz-go делает auto-commit каждые 5 секунд. При краше после обработки и до commit - события будут переданы повторно (at-least-once). Что именно коммитит авто-коммит - разобрано ниже.
Manual Commit для надёжной обработки
client, err := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
kgo.ConsumerGroup("analytics"),
kgo.ConsumeTopics("lesson-events"),
kgo.DisableAutoCommit(),
)
for {
fetches := client.PollFetches(ctx)
if ctx.Err() != nil {
return
}
var toCommit []*kgo.Record
var fatal error
fetches.EachPartition(func(p kgo.FetchTopicPartition) {
for _, r := range p.Records {
if fatal != nil {
return
}
if err := process(r); err != nil {
// Пропустить запись нельзя: если дальше в этой партиции
// обработается хоть одна, коммит перешагнёт через упавшую.
// Откладываем её в DLQ-топик и только тогда идём дальше.
if dErr := sendToDLQ(ctx, client, r, err); dErr != nil {
fatal = fmt.Errorf("%s/%d@%d: %w", r.Topic, r.Partition, r.Offset, dErr)
return
}
}
toCommit = append(toCommit, r)
}
})
if len(toCommit) > 0 {
// Свой контекст: коммит должен пройти и после сигнала остановки
commitCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
if err := client.CommitRecords(commitCtx, toCommit...); err != nil {
log.Printf("commit error: %v", err)
}
cancel()
}
if fatal != nil {
// Клиент уже продвинул позицию чтения за упавшую запись и в этой
// сессии её не отдаст. Выходим с ошибкой: после перезапуска чтение
// начнётся с последнего коммита, и запись придёт снова.
log.Printf("stop consumer: %v", fatal)
return
}
}
// sendToDLQ кладёт запись с текстом ошибки в отдельный топик для разбора.
func sendToDLQ(ctx context.Context, client *kgo.Client, r *kgo.Record, cause error) error {
headers := append([]kgo.RecordHeader{}, r.Headers...)
headers = append(headers, kgo.RecordHeader{Key: "error", Value: []byte(cause.Error())})
dlq := &kgo.Record{Topic: r.Topic + ".dlq", Key: r.Key, Value: r.Value, Headers: headers}
return client.ProduceSync(ctx, dlq).FirstErr()
}
CommitRecords коммитит offset для каждой партиции по максимальному offset в переданном списке. Поэтому внутри партиции нельзя «перепрыгнуть» через упавшую запись: её нужно либо обработать (повторить с паузой), либо надёжно отложить в DLQ-топик, и только потом коммитить то, что идёт после неё.
Авто-коммит: что за ним скрывается
В franz-go авто-коммит по умолчанию фиксирует offset-ы записей из предыдущих вызовов PollFetches, а не из текущего: записи последнего poll считаются «грязными» и ждут следующего poll. Если обрабатывать записи синхронно до следующего PollFetches, это at-least-once:
PollFetches → получены записи 100-120 (они «грязные», авто-коммит их не трогает)
обработка записей 100-115...
краш приложения
→ при перезапуске: читаем снова с 100 (ok, at-least-once, 100-115 придут повторно)
Потеря возможна в двух случаях:
- обработка асинхронная: записи отправлены в горутины, а цикл уже сделал следующий
PollFetches- для авто-коммита они «чистые», хотя ещё в работе; - включён
kgo.GreedyAutoCommit(): он коммитит всё опрошенное, включая последний poll.
В клиентах на librdkafka (confluent-kafka-go, php-rdkafka) поведение другое: там авто-коммит может зафиксировать offset записей, которые уже отданы приложению, но ещё не обработаны. Поэтому общее правило такое: если обработка асинхронная или важно точно контролировать момент фиксации (например, коммит после записи в БД), используй manual commit.
Параллельная обработка
fetches := client.PollFetches(ctx)
var wg sync.WaitGroup
var mu sync.Mutex
var toCommit []*kgo.Record
var failed bool
fetches.EachPartition(func(p kgo.FetchTopicPartition) {
// Обрабатываем каждую партицию в своей горутине
// Порядок внутри партиции сохраняется
wg.Add(1)
go func(p kgo.FetchTopicPartition) {
defer wg.Done()
for _, r := range p.Records {
if err := process(r); err != nil {
// Дальше по этой партиции не идём: коммит не должен
// перешагнуть через необработанную запись (см. выше)
log.Printf("process %d@%d: %v", r.Partition, r.Offset, err)
mu.Lock()
failed = true
mu.Unlock()
return
}
mu.Lock()
toCommit = append(toCommit, r)
mu.Unlock()
}
}(p)
})
wg.Wait()
if len(toCommit) > 0 {
if err := client.CommitRecords(ctx, toCommit...); err != nil {
log.Printf("commit error: %v", err)
}
}
if failed {
return // перезапуск перечитает партицию с последнего коммита
}
Разные партиции обрабатываются параллельно (порядок между ними всё равно не гарантирован). Внутри одной партиции - последовательно.
Rebalance: hooks
Kafka выполняет rebalance при добавлении/удалении consumer-а. При старом eager-протоколе на время rebalance все consumer-ы группы останавливают чтение. В franz-go по умолчанию балансировщик cooperative-sticky (incremental rebalance): отбираются только переезжающие партиции, остальные читаются без паузы. В Kafka 4.x есть ещё и новый серверный протокол групп (KIP-848), который тоже работает инкрементально. franz-go уведомляет о переездах через хуки:
client, _ := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
kgo.ConsumerGroup("analytics"),
kgo.ConsumeTopics("lesson-events"),
kgo.DisableAutoCommit(),
// Rebalance не начнётся посреди обработки пачки: клиент ждёт,
// пока цикл не вызовет client.AllowRebalance()
kgo.BlockRebalanceOnPoll(),
kgo.OnPartitionsAssigned(func(ctx context.Context, c *kgo.Client, assigned map[string][]int32) {
for topic, partitions := range assigned {
log.Printf("assigned: topic=%s partitions=%v", topic, partitions)
}
}),
kgo.OnPartitionsRevoked(func(ctx context.Context, c *kgo.Client, revoked map[string][]int32) {
// Перед тем как отдать партиции - блокирующий commit всего опрошенного.
// Это безопасно, потому что благодаря BlockRebalanceOnPoll хук
// вызывается только после того, как пачка полностью обработана.
if err := c.CommitUncommittedOffsets(ctx); err != nil {
log.Printf("commit on revoke: %v", err)
}
}),
)
for {
fetches := client.PollFetches(ctx)
// ... обработка и CommitRecords, как выше ...
client.AllowRebalance() // пачка обработана - теперь rebalance можно
}
OnPartitionsRevoked - правильное место для финального commit. Без него при rebalance возможна повторная обработка. Важно, какой метод вызывать: CommitMarkedOffsets коммитит только записи, помеченные MarkCommitRecords в режиме kgo.AutoCommitMarks(), а с DisableAutoCommit он ничего не делает. При ручном коммите используют CommitRecords (по списку обработанных) или CommitUncommittedOffsets (если обработаны все опрошенные записи).
Consumer Lag
Consumer lag = latest_offset - committed_offset. Растущий lag означает, что consumer не успевает за producer-ом.
# Проверить lag через CLI
docker exec kafka kafka-consumer-groups \
--bootstrap-server localhost:9092 \
--describe \
--group analytics
# Вывод:
# GROUP TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG
# analytics lesson-events 0 1000 1050 50
# analytics lesson-events 1 800 800 0
# analytics lesson-events 2 600 650 50
Lag > 0 - нормально при кратких всплесках. Постоянно растущий lag - нужно масштабировать consumer group (добавить воркеры) или оптимизировать обработку. Смотреть lag глазами в CLI годится один раз; в продакшне его снимают kafka-exporter и kprom, а на рост вешают alert rule - мониторинг Kafka.
Graceful Shutdown
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
go func() {
<-ctx.Done()
log.Println("shutdown signal received")
// PollFetches вернёт после отмены контекста
}()
for {
fetches := client.PollFetches(ctx)
if ctx.Err() != nil {
// Записи из этого последнего poll не обрабатываем и не коммитим:
// после перезапуска их прочитает этот или другой воркер.
// Всё обработанное раньше уже закоммичено после каждой пачки
// (CommitRecords со своим контекстом, как в разделе про manual commit).
return
}
// обработка + CommitRecords...
}
client.Close() отправляет запрос LeaveGroup - Kafka выполняет rebalance немедленно, а не ждёт сессионный таймаут (по умолчанию 45 секунд).
Consume без group (standalone)
ConsumeResetOffset задаёт, откуда читать, когда закоммиченного offset ещё нет (группа стартует впервые) или он устарел: kgo.NewOffset().AtStart() - с начала топика, AtEnd() - только новые сообщения. В franz-go по умолчанию - с начала.
// Читать с начала, без consumer group - для утилит и отладки
client, _ := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
kgo.ConsumeTopics("lesson-events"),
kgo.ConsumeResetOffset(kgo.NewOffset().AtStart()),
)
// Или читать конкретный диапазон партиций
client, _ := kgo.NewClient(
kgo.SeedBrokers("localhost:9092"),
kgo.ConsumePartitions(map[string]map[int32]kgo.Offset{
"lesson-events": {
0: kgo.NewOffset().At(100), // с offset 100 партиции 0
},
}),
)
Без ConsumerGroup - нет координации, нет rebalance. Один процесс читает все партиции сам.
Типичные ошибки
Больше воркеров чем партиций - лишние воркеры простаивают и не получают партиций. При 3 партициях максимум 3 активных consumer-а в группе.
Не обрабатывать ctx.Err() после PollFetches - при отмене контекста PollFetches возвращает пустой Fetches. Без проверки ctx.Err() цикл крутится бесконечно.
Commit до обработки - at-most-once. Если коммитить offset сразу после poll, а потом обрабатывать - при краше во время обработки сообщение потеряно.
Глобальный time.Sleep в обработчике - блокирует партицию полностью. Используй отдельные воркеры per-partition или буферизованный канал.
Смотри также
- Message Brokers - Producer - как отправлять то, что читаем
- Message Brokers - Exactly-once - commit стратегия и гарантии
- Go - Context - отмена через context, signal.NotifyContext
Мини-задание
- Напиши consumer с
DisableAutoCommit()и manualCommitRecordsпосле обработки каждого батча - Запусти двух воркеров с одним
group.idна топике с 3 партициями - выведи в логах какая партиция у каждого - Остановь один воркер - через сколько секунд партиции перераспределились ко второму?
- Отправь 100 событий через producer, затем остановь consumer после 50 - убедись что при перезапуске consumer прочитал ровно оставшиеся 50
- Добавь
BlockRebalanceOnPollиOnPartitionsRevokedhook сCommitUncommittedOffsets