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

オープン 初心者向け
#2,404 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 3 日以内に返信

@hidingmyname がすでに取り組んでいます。

2026年10月29日 から。

  • #2407 @hidingmyname による — オープン

評価

難易度
1/5
見積もり時間
1時間未満
初心者へのやさしさ
91/100
issue の種類
ドキュメント
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
kafka, python
領域
documentation

調査の方向性

src/confluent_kafka/src/Producer.c の init_transactions と begin_transaction の docstring を読み、src/rdkafka.h にある librdkafka のリファレンスと表現を比較してください。トランザクションのタイムアウトに関する説明を begin_transaction に移し、init_transactions から削除してください。Python の docstring が文書化されたタイムアウトの動作と一致すれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
Python
スター
528
フォーク
977
平均マージ
2日 19時間
マージ済み PR(30日)
19

環境構築

  • Dockerfile・Docker Compose ファイルなし
  • プルリクエストのテンプレートあり
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

confluentinc/confluent-kafka-python のほかの issue

confluentinc/confluent-kafka-python の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。