Exactly-once в Kafka: idempotent producer и транзакции

Exactly-once в Kafka: idempotent producer и транзакции

Гарантии доставки - это договор между producer-ом, брокером и consumer-ом. Kafka поддерживает все три уровня, но для каждого нужна конкретная конфигурация.

Теорию мы уже разобрали в event-driven - гарантии доставки. Здесь - как это выглядит в коде.

At-most-once: отправить и забыть

client, _ := kgo.NewClient(
    kgo.SeedBrokers("localhost:9092"),
    kgo.RequiredAcks(kgo.NoAck()),  // не ждать подтверждения
)

client.Produce(ctx, &kgo.Record{
    Topic: "events",
    Value: payload,
}, nil) // callback nil - не обрабатываем ошибки

Producer не ждёт подтверждения. Максимальная скорость, нулевая надёжность. Для метрик и аналитики, где потеря события допустима.

At-least-once: стандартный режим

client, _ := kgo.NewClient(
    kgo.SeedBrokers("localhost:9092"),
    kgo.RequiredAcks(kgo.AllISRAcks()),  // ждать ack от всех in-sync реплик
    kgo.RecordRetries(10),               // retry при временных ошибках
    kgo.RecordDeliveryTimeout(30 * time.Second),
)

При таймауте или сбое сети producer повторяет отправку. Возможны дубликаты, если первая отправка дошла до брокера, но ack потерялся.

Consumer должен уметь обрабатывать дубли - idempotent consumer.

Idempotent Producer

client, _ := kgo.NewClient(
    kgo.SeedBrokers("localhost:9092"),
    kgo.RequiredAcks(kgo.AllISRAcks()),
    // franz-go включает idempotent producer автоматически
    // при AllISRAcks - не нужна явная настройка
)

Idempotent producer присваивает каждой записи уникальный sequence number. Если брокер получает повтор (тот же producer + та же партиция + тот же seq), он отбрасывает дубль. Это защищает от дублей при сетевых retry, которые клиент делает сам. Если же код дважды вызвал Produce для одного события, это две разные записи с разными sequence number, и в топик попадут обе.

Ограничение: идемпотентность гарантируется только в рамках одной сессии producer-а. После перезапуска producer получает новый producer ID и дубли снова возможны.

Транзакции Kafka: exactly-once

Транзакции нужны для сценария read-process-write: прочитал из топика A, обработал, записал в топик B + commit offset. Всё это - атомарно.

⚠️ Граница гарантии проходит по Kafka

Транзакция связывает чтение, запись и коммит offset - и всё это внутри Kafka. Никакой побочный эффект за её пределами она не откатывает.

Списали деньги в PostgreSQL, отправили письмо, дёрнули чужой API - и упали до коммита? Kafka честно отдаст сообщение заново, и эффект повторится. Поэтому строка «exactly-once - для финансовых операций» (а её пишут часто) вводит в заблуждение: если деньги двигаются в базе, транзакция Kafka о них не знает.

Для внешних эффектов работает другая пара: at-least-once плюс идемпотентность обработчика - ключ операции, проверка «уже делали» и запись результата в той же транзакции базы. А чтобы событие и запись в базу не разъехались в момент публикации, нужен transactional outbox.

Во franz-go для схемы «прочитал в группе - записал - закоммитил offset» есть готовая обёртка GroupTransactSession. Это один клиент, который одновременно consumer группы и транзакционный producer: он сам добавляет offset-ы группы в транзакцию и сам откатывает её, если посреди работы случился rebalance. Отдельного метода «добавить offset-ы в транзакцию» у kgo.Client нет - этим и занимается сессия.

sess, err := kgo.NewGroupTransactSession(
    kgo.SeedBrokers("localhost:9092"),
    kgo.TransactionalID("analytics-processor-1"), // уникальный per-instance
    kgo.ConsumerGroup("analytics"),
    kgo.ConsumeTopics("lesson-events"),
    // Читать только закоммиченные транзакции (по умолчанию - все записи)
    kgo.FetchIsolationLevel(kgo.ReadCommitted()),
    // Не отдавать offset-ы, по которым ещё висит незавершённая транзакция
    kgo.RequireStableFetchOffsets(),
)
if err != nil {
    log.Fatal(err)
}
defer sess.Close()
for {
    fetches := sess.PollFetches(ctx)
    if ctx.Err() != nil {
        return
    }

    // Начинаем транзакцию
    if err := sess.Begin(); err != nil {
        log.Printf("begin transaction: %v", err)
        return // ошибка состояния клиента - продолжать нельзя
    }

    var produceErr error
    fetches.EachRecord(func(r *kgo.Record) {
        if produceErr != nil {
            return
        }
        result := processRecord(r) // бизнес-логика
        out := &kgo.Record{
            Topic: "analytics-output",
            Value: result,
        }
        if err := sess.ProduceSync(ctx, out).FirstErr(); err != nil {
            produceErr = err
        }
    })

    // End коммитит в одной транзакции и записи в analytics-output,
    // и offset-ы группы для прочитанных записей. TryAbort - откат всего.
    // Если во время работы был rebalance, End сам сделает abort,
    // даже если мы просили commit, и вернёт committed = false.
    action := kgo.TryCommit
    if produceErr != nil {
        log.Printf("produce: %v", produceErr)
        action = kgo.TryAbort
    }
    committed, err := sess.End(ctx, action)
    if err != nil {
        log.Printf("end transaction: %v", err)
        return
    }
    if !committed {
        // Транзакция откатилась: offset-ы не сдвинулись, и эти записи
        // группа прочитает снова (этот или другой воркер после rebalance)
        log.Printf("transaction aborted, records will be re-read")
    }
}

Offset-ы группы коммитятся внутри той же транзакции, что и записи в analytics-output. Если транзакция откатится, offset тоже не применится, и записи будут прочитаны заново.

Если нужна просто атомарная запись в несколько партиций или топиков без чтения из группы, хватает обычного kgo.Client с kgo.TransactionalID. Шаги те же, только методы называются иначе: client.BeginTransaction() → Produce/ProduceSync → client.EndTransaction(ctx, kgo.TryCommit) (или kgo.TryAbort для отката).

Acks: параметр надёжности

// Ack уровни
kgo.NoAck()         // 0 - не ждать ответа брокера
kgo.LeaderAck()     // 1 - ждать подтверждения от лидера партиции
kgo.AllISRAcks()    // -1 - ждать от всех in-sync реплик

ISR (In-Sync Replicas) - реплики, которые синхронизированы с лидером. При AllISRAcks запись считается сохранённой только когда все ISR-реплики её подтвердили. Это защита от потери при падении лидера сразу после записи.

В dev-окружении с одним брокером AllISRAcks = LeaderAck (одна реплика в ISR). В продакшне с replication factor 3 - более строгая гарантия.

Когда что выбирать

ГарантияПрименениеКонфигурация
At-most-onceМетрики, некритичные логиNoAck, callback nil
At-least-onceСобытия, нотификацииAllISRAcks + idempotent consumer
Exactly-once внутри KafkaПотоковая обработка: топик → топикТранзакции + FetchIsolationLevel(ReadCommitted)

На практике at-least-once + idempotent consumer покрывает 95% случаев. Транзакции нужны только для read-process-write потоков. И учти границу: любые acks и idempotent producer защищают участок «producer - брокер». Если событие рождается вместе с записью в PostgreSQL, между COMMIT и Publish остаётся щель, и закрывает её только transactional outbox.

Типичная ошибка

TransactionalID один на несколько инстансов - два процесса с одним TransactionalID фенсируют друг друга: при старте второго первый получает ошибку PRODUCER_FENCED. TransactionalID должен быть уникальным per-pod, обычно включает hostname или pod-индекс. Механизм за этим называется fencing: при старте producer-а брокер увеличивает его epoch - счётчик поколения для этого TransactionalID. Записи от инстанса со старым epoch отвергаются. Так «зомби» - старый инстанс, который завис, а после рестарта замены очнулся - не может дописать в чужую транзакцию.

FetchIsolationLevel не установлен - consumer читает uncommitted записи из транзакций, которые позже могут быть отменены. Включай ReadCommitted на consumer-стороне.

Транзакции там, где не нужны - транзакции снижают throughput. Для простых событий достаточно at-least-once + idempotency key в payload.

Смотри также

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

  • Напиши producer с AllISRAcks и отправь 10 событий, убедись что все дошли
  • Намеренно отправь одну запись дважды (два вызова ProduceSync с одинаковым ключом) и убедись, что в топике две записи: idempotent producer защищает только от дублей при своих внутренних ретраях (тот же producer id, партиция и sequence number), а не от повторного вызова Produce. Повторные отправки отбрасывает consumer по event_id
  • Реализуй транзакционный processor на GroupTransactSession: читай из input-topic, обрабатывай, пиши в output-topic с commit offset атомарно
  • Попробуй запустить два процесса с одним TransactionalID - что происходит?
  • Для своего проекта: определи нужный уровень гарантии для каждого типа событий

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