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

Abierto Apto para principiantes
#2,404 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 3 días

@hidingmyname ya está trabajando en esto.

Desde el 29/10/2026.

  • #2407 de @hidingmyname — abierto

Evaluación

Dificultad
1/5
Tiempo estimado
Menos de una hora
Aptitud para principiantes
91/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
kafka, python

Línea de trabajo

Lee los docstrings de init_transactions y begin_transaction en src/confluent_kafka/src/Producer.c y compara su redacción con la referencia de librdkafka en src/rdkafka.h. Mueve la explicación del tiempo de espera de la transacción a begin_transaction y elimínala de init_transactions; el trabajo estará terminado cuando los docstrings de Python coincidan con el comportamiento documentado del tiempo de espera.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
528
Forks
977
Merge medio
2 d 19 h
PR fusionados (30 d)
19

Preparar el entorno

  • Sin Dockerfile ni archivo de Docker Compose
  • Tiene una plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de confluentinc/confluent-kafka-python

Todos los issues de confluentinc/confluent-kafka-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.