init_transactions docstring says the transaction.timeout.ms clock starts there; it starts at begin_transaction

Aperta Adatta ai principianti
#2,404 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 3 giorni

@hidingmyname ci sta già lavorando.

Dal 29/10/2026.

  • #2407 di @hidingmyname — aperta

Valutazione

Difficoltà
1/5
Tempo stimato
Meno di un'ora
Idoneità per principianti
91/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
kafka, python
Ambito
documentation

Direzione di ricerca

Leggi le docstring di init_transactions e begin_transaction in src/confluent_kafka/src/Producer.c e confrontane la formulazione con il riferimento librdkafka in src/rdkafka.h. Sposta la spiegazione del timeout della transazione in begin_transaction e rimuovila da init_transactions; il lavoro è concluso quando le docstring Python corrispondono al comportamento del timeout documentato.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Description

src/confluent_kafka/src/Producer.c, in the init_transactions docstring:

"  Upon successful return from this function the application has to\n"
"  perform at least one of the following operations within \n"
"  `transaction.timeout.ms` to avoid timing out the transaction\n"
"  on the broker:\n"
"  * produce() (et.al)\n"
"  * send_offsets_to_transaction()\n"
"  * commit_transaction()\n"
"  * abort_transaction()\n"

This belongs on begin_transaction. The transaction timeout applies to an open
transaction, and nothing is open when init_transactions returns — the broker
has no transaction to time out. The clock starts when begin_transaction
succeeds.

librdkafka documents it that way, on rd_kafka_begin_transaction
(src/rdkafka.h):

/**
 * @brief Begin a new transaction.
 *
 * rd_kafka_init_transactions() must have been called successfully (once)
 * before this function is called.
 *
 * Upon successful return from this function the application has to perform at
 * least one of the following operations within \c transaction.timeout.ms to
 * avoid timing out the transaction on the broker:
 *   * rd_kafka_produce() (et.al)
 *   ...

and rd_kafka_init_transactions doesn't mention the timeout. The Python
begin_transaction docstring currently has no mention of it either.

Why it matters

The common pattern is init_transactions() once at startup, then
begin_transaction() per batch. This docstring makes it look like the idle gap
after init is on a clock — so people either rush the first transaction or add
keepalive logic for a timeout that isn't running. And the place where the
timeout genuinely bites, a long-running open transaction, carries no warning.

Suggested fix

Move the paragraph from init_transactions to begin_transaction, matching
librdkafka and the Go client:

      "  will acquire the internal producer id and epoch, used in all\n"
      "  future transactional messages issued by this producer instance.\n"
-     "\n"
-     "  Upon successful return from this function the application has to\n"
-     "  perform at least one of the following operations within \n"
-     "  `transaction.timeout.ms` to avoid timing out the transaction\n"
-     "  on the broker:\n"
-     "  * produce() (et.al)\n"
-     "  * send_offsets_to_transaction()\n"
-     "  * commit_transaction()\n"
-     "  * abort_transaction()\n"
      "\n"
      "  :param float timeout: Maximum time to block in seconds.\n"
      "  init_transactions() must have been called successfully (once)\n"
      "  before this function is called.\n"
      "\n"
+     "  Upon successful return from this function the application has to\n"
+     "  perform at least one of the following operations within\n"
+     "  `transaction.timeout.ms` to avoid timing out the transaction\n"
+     "  on the broker:\n"
+     "  * produce() (et.al)\n"
+     "  * send_offsets_to_transaction()\n"
+     "  * commit_transaction()\n"
+     "  * abort_transaction()\n"
+     "\n"
      "  Any messages produced or offsets sent to a transaction, after\n"
Upstream reference

librdkafka moved this note in a6f81818 ("move note about transaction.timeout.ms
to begin_transaction", 2020-12-09) — removed from
rd_kafka_init_transactions() and added to rd_kafka_begin_transaction():

--- a/src/rdkafka.h
+++ b/src/rdkafka.h
@@ -6951,14 +6951,6 @@
  * will acquire the internal producer id and epoch, used in all future
  * transactional messages issued by this producer instance.
  *
- * Upon successful return from this function the application has to perform at
- * least one of the following operations within \c transaction.timeout.ms to
- * avoid timing out the transaction on the broker:
- *   * rd_kafka_produce() (et.al)
- *   * rd_kafka_send_offsets_to_transaction()
- *   * rd_kafka_commit_transaction()
- *   * rd_kafka_abort_transaction()
- *
  * @param rk Producer instance.
@@ -7007,6 +6999,14 @@
  * rd_kafka_init_transactions() must have been called successfully (once)
  * before this function is called.
  *
+ * Upon successful return from this function the application has to perform at
+ * least one of the following operations within \c transaction.timeout.ms to
+ * avoid timing out the transaction on the broker:
+ *   * rd_kafka_produce() (et.al)
+ *   * rd_kafka_send_offsets_to_transaction()
+ *   * rd_kafka_commit_transaction()
+ *   * rd_kafka_abort_transaction()
+ *
  * Any messages produced, offsets sent (rd_kafka_send_offsets_to_transaction()),

confluent-kafka-go applied the same move in confluentinc/confluent-kafka-go@89b6c2c
("Move doc from InitTransactions to BeginTransaction",
confluentinc/confluent-kafka-go#1095, 2024-01-10):

--- a/kafka/producer.go
+++ b/kafka/producer.go
@@ -807,14 +807,6 @@
 // will acquire the internal producer id and epoch, used in all future
 // transactional messages issued by this producer instance.
 //
-// Upon successful return from this function the application has to perform at
-// least one of the following operations within `transaction.timeout.ms` to
-// avoid timing out the transaction on the broker:
-//   - `Produce()` (et.al)
-//   - `SendOffsetsToTransaction()`
-//   - `CommitTransaction()`
-//   - `AbortTransaction()`
-//
 // Parameters:
@@ -846,6 +838,14 @@
 // `InitTransactions()` must have been called successfully (once)
 // before this function is called.
 //
+// Upon successful return from this function the application has to perform at
+// least one of the following operations within `transaction.timeout.ms` to
+// avoid timing out the transaction on the broker:
+//   - `Produce()` (et.al)
+//   - `SendOffsetsToTransaction()`
+//   - `CommitTransaction()`
+//   - `AbortTransaction()`
+//
 // Any messages produced, offsets sent (`SendOffsetsToTransaction()`),

So C and Go agree; Python and .NET are the two clients still carrying it in the
old place.

I can submit a PR for this.

Lingua principale
Python
Stelle
528
Fork
977
Merge medio
2g 19h
PR unite (30g)
19

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di confluentinc/confluent-kafka-python

Tutte le issue di confluentinc/confluent-kafka-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.