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 или буферизованный канал.

Смотри также

Мини-задание

  • Напиши consumer с DisableAutoCommit() и manual CommitRecords после обработки каждого батча
  • Запусти двух воркеров с одним group.id на топике с 3 партициями - выведи в логах какая партиция у каждого
  • Остановь один воркер - через сколько секунд партиции перераспределились ко второму?
  • Отправь 100 событий через producer, затем остановь consumer после 50 - убедись что при перезапуске consumer прочитал ровно оставшиеся 50
  • Добавь BlockRebalanceOnPoll и OnPartitionsRevoked hook с CommitUncommittedOffsets

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.