さらに Kafka から取り出したメッセージに何らかの処理を行い再度 Kafka に書き込む、という処理を行うにあたっては Offset Commit もトランザクションに含めることができます。

この記事ではトランザクションを用いて送信したメッセージが後段で読まれるまでの流れを説明し、さらに Offset Commit をトランザクション内で行う際の流れについても説明します。

Kafka バージョンは 4.1.0 を用います。

トランザクションでメッセージを送る流れ

メッセージ送信だけでなく Offset Commit も一つのトランザクションにまとめられるのが Kafka のトランザクションの特徴ですが、まずトランザクションを用いて単純にメッセージを送る流れから説明します。

トランザクションを使用してメッセージを送信する際の大まかな流れは以下の通りです (すべて正常に送信できた場合)。

1. トランザクションを初期化
2. トランザクションを開始
3. メッセージを送信 (ここでは送信先は Topic A)
4. トランザクションを Commit

このように大まかな流れはデータベースのトランザクションと同様です。そして各ステップでそれぞれ以下のメソッドが対応します。

1. トランザクションを初期化 (initTransactions メソッド)
2. トランザクションを開始 (beginTransaction メソッド)
3. メッセージを送信 (send メソッド)
4. トランザクションを Commit (commitTransaction メソッド)

また送信中に例外が起きた場合などは abortTransaction メソッドによりトランザクションを Abort します。これらはすべて Producer のメソッドです。

トランザクションの挙動

ここからは各メソッドがどのように動作するかを説明します。

1. トランザクションの初期化 (initTransactions)

まずトランザクションを利用する前に initTransactions を呼び出します。このメソッドでは Transaction Coordinator に InitProducerId リクエストを送信してトランザクション初期化の処理を行います。InitProducerId リクエストには TransactionalID が含まれています。これは Producer のパラメータで、トランザクションを識別できるようにクラスタ内で一意になるよう設定します。初期化処理ではこの ID をもとに Transaction Coordinator から Producer ID を取得します。initTransactions は Producer 起動時に 1 回実行する必要があります。

2. トランザクションの開始 (beginTransaction)

次に beginTransaction メソッドによってトランザクションを開始します。このメソッドでは Transaction Coordinator にリクエストを送るわけではなく Producer 内部の状態を変更することでトランザクションを開始します。

3. メッセージを送信 (send)

メッセージの送信は通常の送信と同様 send メソッドを用います。基本的には通常の送信と同じ挙動なのですが、Broker はトランザクション中の Produce リクエストを受け取るとメッセージの書き込みの前に (未実施であれば) AddPartitionsToTxn というリクエストを Transaction Coordinator に送ります。このリクエストでは書き込み先の Topic と Partition を Transaction Coordinator に知らせ、__transaction_state というトランザクション管理用内部 Topic に記録します。これによってどの Partition がトランザクション中なのか記録することができます。

4. トランザクションを Commit/Abort (commitTransaction/abortTransaction)

必要なメッセージ送信が完了したら commitTransaction によってトランザクションを確定させます。commitTransaction ではトランザクションを Commit する旨を添えて EndTxn リクエストを Transaction coordinator に送ります。Transaction coordinator がリクエストを受け取るとまず __transaction_state に Commit する旨を記録します。さらに AddPartitionsToTxn によって記録されている Partition に対して Commit したことを示すメッセージを送ります。このメッセージは Control Batch と呼ばれる、トランザクションの終了を示す特別なメッセージです。Control Batch の送信は commitTransaction とは非同期で行われます。

トランザクションを Abort するには abortTransaction を用います。abortTransaction ではトランザクションを Abort する旨を添えて EndTxn リクエストを送り、関連する Partition に Abort したことを示す Control Batch を送ります。

Commit / Abort がされた状態の Partition は下図のようになっています。Control Batch も通常のメッセージと同じように記録されます。

トランザクションで送信したメッセージの読み出し

次にメッセージを読み出す際にトランザクション中のメッセージや Abort したメッセージをどのように扱うかについて説明します。

すでに述べたように、トランザクションの Commit / Abort は Control Batch によって行うのでトランザクション中のメッセージも Partition 内には記録されています。また Abort したメッセージも Partition 内には残っています。これらのメッセージをどのように扱うかは Consumer の設定である isolation.level によって決まります。

isolation.level には read_uncommitted (デフォルト値) あるいは read_committed を設定することができます。read_uncommitted の場合、poll メソッドはトランザクション中かどうかや Abort されているかに関わらずすべてのメッセージを取得することができます。

次に read_committed の場合ですが、この説明のためには Last Stable Offset (LSO) について説明する必要があります。LSO はトランザクションが未確定の Offset のうち一番小さい Offset のこと (下図では Offset 6) です。これより前の Offset はすべて確定していることになり、Stable Offsets といいます。逆にこれより後の Offset の領域では確定と未確定が混在していることになります。混在しうるのは同じ Partition に複数の Producer がトランザクションでメッセージを送信する場合です。read_committed の場合、poll メソッドは Stable Offsets のメッセージのみ取得することができます。さらに Abort されたメッセージを取り除いた上でユーザーに返します。

このように、トランザクションを使って送信したメッセージを読み出す際は isolation.level を read_committed にすることで Commit 済みのメッセージのみ読むことができます。

トランザクションと Offset Commit

冒頭で述べたように、Offset Commit をトランザクションに含められる点が Kafka のトランザクションの特徴です。この仕組みは、Kafka から取得したメッセージに何らかの処理を行い、再度 Kafka に書き込むような処理で利用されます。

この例では以下の流れで処理が進みます。

1. クライアント AP が Topic A からメッセージを取得
2. 取得したメッセージを AP で処理し、その結果を Topic A’ に送信
3. すべての処理結果送信が完了したら Topic A の Offset Commit

ここで Offset Commit がトランザクションに入らない場合を考えてみましょう。処理結果の送信がアトミックにできたとしても Offset Commit に失敗した場合メッセージの取得からやり直すことになり、処理結果が二重に記録されてしまいます。Offset Commit がトランザクションに入れば、Offset Commit に失敗した時に Abort することができます。

このような利点があるため、Kafka から取得したメッセージに何らかの処理を行い、再度 Kafka に書き込むという処理では Offset Commit をトランザクション内で行います。

Offset Commit をトランザクション内で行う際の挙動

Kafka ではトランザクション内で Offset Commit をするために Producer 側で sendOffsetsToTransaction というメソッドが用意されています。全体の流れで見るとトランザクションを Commit する前に sendOffsetsToTransaction をすることになります。

1. トランザクションを初期化 (initTransactions メソッド)
2. Topic A からメッセージを取り出す (Consumer が poll メソッドで取得)
3. トランザクションを開始 (beginTransaction メソッド)
4. 処理結果のメッセージを Topic A’ に送信 (send メソッド)
5. Topic A について Offset Commit (sendOffsetsToTransaction メソッド)
6. トランザクションを Commit (commitTransaction メソッド)

sendOffsetsToTransaction では TxnOffsetCommit リクエストを Consumer Group Coordinator に送ります。Offset Commit のやり方自体は通常の Consumer から行うものと同じで、__consumer_offsets という内部 Topic へ Offset Commit の情報が記録されます。異なるのは内部 Topic への記録の前に (未実施であれば) AddPartitionsToTxn リクエストが送信される点です。send と同様に、この操作によってトランザクションに含まれる Partition の情報が __transaction_state に記録されます。

Offset Commit 情報の Commit (あるいは Abort) も、__consumer_offsets の対応する Partition に Control Batch を送ることによって記録されます。

終わりに

Kafka でトランザクションを用いてメッセージを送信し確定させるまでの挙動と、トランザクションで送信したメッセージを読み出す際の挙動について解説しました。さらに Offset Commit をトランザクション内で行う際の挙動についても解説しました。

Kafka のトランザクションで Offset Commit を行う場合、本来 Consumer から行うものを Producer から行うため混乱しますが、単にメッセージを送るのみであれば使う流れはデータベースのトランザクションと同じようなものです。メッセージを送るのみの流れ、Offset Commit もする場合の流れと段階的に理解するのがよいでしょう。

この記事は SRA Advent Calendar 2025 の20日目の記事です。

Apache Kafka（以下 Kafka）には送達保証のための機能がいくつかあります。 この記事ではその中でも送達が重複するのを防止するための機能である Idempotent Producer について解説します。

Idempotent Producer は Kafka のバージョン 0.11.0.0 からある機能です。この記事ではバージョン 4.1.0 を元に解説します。

Kafka について

Kafka はストリーミング処理を実現するための OSS です。

Kafka では Producer と呼ばれるクライアントが Broker と呼ばれるサーバにデータを送信します。Broker は複数台で Kafka クラスタを構成します。Kafka ではやり取りする一つ一つのデータを Message と呼びます。 そして Consumer と呼ばれるクライアントが Broker からデータを読み出し処理、活用します。

今回紹介する Idempotent Producer は Broker に重複した Message が送られてきた時にそれを排除する機能です。 ではどのように重複は発生し、またそれはどのように排除されるのでしょうか。

Producer の自動リトライ機能

Producer から Broker に送られる Message に重複が発生するのは Producer の自動リトライ機能によるものです。まずこちらについて説明します。

Producer は Message を送ったあと Broker 側から送信が成功したかについての応答として Ack を受け取ります。この Ack をもとに Producer 側で判断して自動で Message 送信をリトライするのが自動リトライ機能です。 以下の図では送信の失敗を正しく検知し再送しています。このように自動リトライ機能は Message を確実に送るために重要な機能です。

自動リトライ機能は Producer の retries という設定値によって制御できます。 送信失敗時、Producer はこの値の回数だけ再送を試みます（0に設定すると自動再送を行いません）。ただし致命的なエラーが起こった時や delivery.timeout.ms というタイムアウト超過時などはそれ以上再送しません。 その場合はユーザー処理で再送することになりますが、そのような再送は Producer による自動リトライではないので区別されます。

さて、以上が自動リトライ機能の概要ですが、この仕組みでは以下の図のように送信には成功したのに Ack が受け取れず再送してしまう可能性があります。重複はこのようにして発生します。

Idempotent Producer（重複排除機能付きの Producer）

自動リトライによって Message が重複して記録されてしまうのを防ぐのが Idempotent Producer の機能です。次はこちらについて説明します。

この機能では Producer は各 Message に1ずつ増加するシーケンス番号を自動で割り当て、Producer ID とともに送信します。 こうすることで Broker 側では、同じ Producer から同じ Message が来たことを検知します。 以下の図のように、Broker はそれを検知した場合重複している Message を Broker 側に記録しません。 さらに、これだけでは Producer は送信が成功したか分からず再送し続けてしまうため、Broker 側は送信成功の Ack を返します。こうすることで Broker 側では Message は重複しませんし、Producer 側で再送し続けることもありません。

Idempotent Producer の重複排除で注意すべきは、検知できるのは自動リトライによる問題という点です。例えば「Producer に障害があって再起動した」という場合は元の Producer とは別の Producer として Broker は認識するので重複があっても気付けません。 また、「自動リトライでは送りきれなかったのでユーザー処理で再送する」という場合も元の Message とは別の Message として Broker は認識するので重複に気付けません。

また Idempotent Producer を有効にするには設定値が以下の条件を満たしている必要があります。デフォルトの設定ではこれらは満たされているので、Idempotent Producer はデフォルトで有効です。

重複排除のソースコード

最後に、Message の重複を検知し排除している部分を Kafka 4.1.0 のソースコードで見てみましょう。 重複の確認は UnifiedLog の append() メソッド内で行っています。このメソッドは送られてきた Message の記録をし、 記録の結果（メソッド内では appendInfo という名前）を返すメソッドです。以下はそこからの抜粋です。

// now that we have valid records, offsets assigned, and timestamps updated, we need to
// validate the idempotent/transactional state of the producers and collect some metadata
AnalyzeAndValidateProducerStateResult result = analyzeAndValidateProducerState(
        logOffsetMetadata, validRecords, origin, verificationGuard);

if (result.maybeDuplicate.isPresent()) {
    BatchMetadata duplicate = result.maybeDuplicate.get();
    appendInfo.setFirstOffset(duplicate.firstOffset());
    appendInfo.setLastOffset(duplicate.lastOffset);
    appendInfo.setLogAppendTime(duplicate.timestamp);
    appendInfo.setLogStartOffset(logStartOffset);
} else {
    // Append the records, and increment the local log end offset immediately after the append because a

analyzeAndValidateProducerState() メソッド内で重複の確認をしており、その結果を result として受け取っています。その結果で result.maybeDuplicate.isPresent() が True だと重複があることが分かります。続く if 文では重複があるか判定していますが、重複がない場合は else 節に存在する Message 記録の処理が行われ、appendInfo に値がセットされます。 重複がある場合は else 節に入らないため Message の記録は行いません。これによって重複は排除されます。また、記録はしませんが appendInfo に値をセットし正常に Message の記録が行われたときと同じ状態にします。このようにすることで Producer には正常に Message が記録されていることが伝わります。

おわりに

Idempotent Producer の仕組みについて解説しました。 重複を排除するというありがたい機能なので、仕組みを理解し適切に活用しましょう。

はじめに

Current はデータストリーミング分野の第一人者が一堂に会するコミュニティイベントです。イベントでは主に Apache Kafka® (以下 Kafka) や Apache Flink® (以下 Flink) などのストリーミング処理ソフトウェアに関する講演が行われ、世界中の人々が集まり交流、学び、そして情報共有する場です。

今年 2025 年は 3 月 19 日にインドのベンガルール、5 月 20 日にイギリスのロンドン、そして 10 月 29 日にアメリカのニューオーリンズで開催されました。今回はその中のニューオーリンズで開催されたイベントに参加してきましたので、私が聴講したセッションを中心にその様子をお伝えしたいと思います。

開催地、ニューオーリンズ

開催地であるニューオーリンズはアメリカのルイジアナ州南部にあるメキシコ湾に面した港湾都市です。ジャズの発祥地として有名で、フレンチクォータと呼ばれる地域ではフランス・スペイン植民地時代の街並みが残り、クレオール、ケイジャン料理などの美食も味わえる全米でも有数の観光都市でもあります。

イベント会場の様子

Current New Orleans 2025 はニューオーリンズの中心部、ミシシッピ川沿岸の Ernest N. Morial Convention Center (アーネスト N. モリアル コンベンションセンター) の一角で開催され、60 以上のセッションに 3,500 人以上が参加する非常に大規模なイベントとなりました。イベントホール内では 50 近いスポンサーブースが立ち並び、各社が提供するデータストリーミングに関する様々なソリューションの紹介や参加者同士の交流の場となっていました。

それ以外にもイベントホール内ではハッカソンが開催されていたり、VR の体験、ストリーミング処理ともかかわりの深い AI に関するアートの展示など、様々なイベントが開催され、大いに盛り上がっていました。

イベントで提供されるセッションは非常に多く複数のセッションが同時に行われていたため、そのすべてをレポートすることはできませんが、その中から私が聴講したものをいくつか紹介したいと思います。

一日目

Keynote (一日目): Building Intelligent Systems on Real-time Data

一日目の Keynoteでは Confluent 社の CEO 兼共同設立者、Jay Kreps 氏がプレゼンターとして壇上に立ちました。Confluent 社はカリフォルニアに本社を置き、Kafka を基盤とした企業向けのリアルタイムデータストリーミングプラットフォームやフルマネージドクラウドサービスを提供する会社で、日本法人として Confluent Japan もあります。また本イベント Current を主催する会社でもあります。

Keynote の主題は昨今の AI の台頭に対して、それを使ったシステムをどう構築し、組織内のソフトウェアそしてリアルタイムのデータとどう結び付けていくかについてです。効果的に AI を活用していくには AI が利用するデータをどのようにアップデートしていくかが重要です。例えばデータの更新をバッチ処理で行うとすればその分最新の状況との差異が生まれます。そこでリアルタイムデータを逐次的に処理できるストリーミングデータパイプラインを構築すれば、常にデータを最新に保ち続けることができます。そのシステムの構築に有効なのが Kafka や Flink といったストリーミング処理のソフトウェアです。企業にとっても日々生まれ続けるデータをリアルタイムに活用するためにはストリーム処理が必要不可欠なのだと感じました。

また Confluent Intelligence と名付けられた新しいサービスもこのセッションの中で発表されました。これはビルトインの機械学習関数、リアルタイムコンテキストエンジン、ストリーミングエージェントの 3 つの製品から構成されるサービスで、AI システムが過去のデータから継続的に学習し、リアルタイムで行動することを可能にするためのものとのことです。AI エージェントや RAG (検索強化生成)、AI 向け機械学習パイプラインの構築、または Kafka および Flink によるコンテキスト提供に活用が期待されるサービスです。

さらには、Confluent Private Cloud の発表も併せて行われました。これは Confluent Platform を基盤としており、自社インフラにクラウドサービスの効率性を備えたプライベートデータストリーミング環境を実現できるサービスとなるようです。

続いて一日目の個別セッションの内容をご紹介します。

Introduction to Apache Flink: Key Concepts and Architecture

ストリーム処理とバッチ処理の両方をサポートする分散処理フレームワークである Flink について解説する、初心者向けのワークショップセッションです。ストリーム処理とバッチ処理の概念や Flink による分散処理のコンセプトとアーキテクチャを基礎から丁寧に解説されており、ストリーム処理を一から学びたいという人にも最適なセッションだと感じました。

A Deep Dive into Kafka Consumer Rebalance Protocols: Mechanisms and Migration Process Insights

Kafka 4.0 で実装された新しい Consumer Rebalance Protocol の詳細について、既存との違いをデモを交えてわかりやすく解説されていました。また、既存のプロトコルからの移行のメカニズムについてもオンラインとオフライン両方に対応した方法を紹介されていました。

Consumer Rebalance Protocol とは、ConsumerGroup 内でどの Partition をどの Consumer に割り当てるかを調整するメカニズムです。従来のプロトコルではグループ内のメンバが変化した際に、リバランスが完了するまで一時的に Consume が停止するという制約がありましたが、新しいプロトコルではそれが軽減・削除されています。また、リバランスによる再割り当てのロジックを Broker 側に移動しており、それによる大幅な高速化や安定性の向上も見込めるという利点もあります。

The Kafka Protocol Deconstructed: A Live-Coded Deep Dive

このセッションでは Kafka が持つ様々な機能を実現する上でどのようなプロトコルを用いているのかを、かなり根本的な部分まで深掘りして解説されていました。例えば、リクエストのヘッダやボディがどういった要素から構成されていて、それぞれの要素にはどういった内容のデータが格納されているかなど、Kafka が実際にやり取りしている通信プロトコルを明らかにし、それを一から再構築するといったところまで実演していました。

プロトコルを深く知ることで Kafka の内部挙動を本質的に理解できると共に、実用上でのチューニングや問題解決にも応用できそうな、私にとっては非常に有用な内容でした。

Current party

一日目の終わりには参加者ならだれでも参加できるパーティが開かれました。時期が近いこともあり、中はハロウィン風の装飾がされていたり、ニューオーリンズらしくライブ演奏やクレオール、ケイジャン料理が味わえたりと様々な趣向が凝らされており、参加者同士の交流を深めるという意味でも非常に有意義なパーティでした。

二日目

Keynote (二日目): Be Ready for What’s Next

二日目の Keynote では Confluent 社のアドボカシーおよびデベロッパーエクスペリエンスエンジニアリング部門責任者の Adi Polak 氏が登場し、リアルタイムシステムの現在までの発展の経緯について語りました。モノリシックなシステムからマイクロサービスへの転換、マイクロサービス同士をつなぐ Kafka の登場、そしてデータレイクとして Apache Hadoop と HDFS から Apache Iceberg、Apache Hudi、Delta Lake といったテーブルフォーマットを導入したことによる信頼性の向上。これらの発展によって今現実に起こっていることをリアルタイムで処理するための準備が整いました。そして現在 AI が登場しました。真に信頼できる AI のためには優れたモデルが必要ですが、それを構築・実用するには信頼できるリアルタイムデータ、ひいてはそれを作り出す信頼できるシステムを準備しておくことが必要であると彼女は述べていました。

このセッションではその他にもテレビ番組のトークショーを模した形式でのデータストリーミング分野の第一人者へのインタビューや、コミュニティやこの分野に貢献した企業への授賞式なども行われました。

続いて二日目の個別セッションの内容をご紹介します。

What Can you do with a (Kafka) Queue?

このセッションでは Kafka をメッセージキューとして利用可能にするための新しい Consumer Group の実装である、Share Group について解説されていました。従来の Consumer Group では Partition 内でのメッセージ順序を維持するために、グループ内で重複して同じ Partition からメッセージを取得することはありませんが、Share Group ではそれを可能にすることでメッセージキューとして Kafka を使うことができるようになります。この機能はまだ完全に実装されてはいませんが、これによって Kafka の用途の可能性が広がる非常に興味深いものだと感じました。

Playing Chess by Scaling Multi-Agent LLM Play with Kafka Queues

これは上記の Kafka のキュー機能を利用して、LLM (大規模言語モデル) にチェスを並列で同時にプレイさせてみたという、中々面白い内容のセッションです。AI と Kafka の新機能を組み合わせることで、アイディアによってはこういう使い方もできるんだという一例だと思います。実際にセッション中にデモを披露していましたが、かなりスムーズに LLM がチェスを複数盤面で同時にプレイする様子も伺えました。

AI 関連のセッション

Keynote で言及もあったように、データストリーミングは AI とも関連の深い分野です。本イベントでも AI に関するセッションは数多くあり、AI Alley Theater という AI セッション専用のブースが設けられるほどでした。

その他のイベントの様子

おわりに

Current はデータストリーミングの現在を肌で感じることのできる唯一のイベントです。私も今回参加したことで、Kafka をはじめとしたストリーミング処理について、最新の動向や深い知見を大いに得ることができ、データストリーミングの分野が今いかにホットであるかということを知ることができました。

セッションの内容も幅広く、初心者向けに Kafka や Flink といったデータストリーミングプラットフォームを構成するソフトウェアの基礎を解説するものや、より深く内部動作を解説するもの、ソリューションや活用例を紹介するものなど、データストリーミングを知りたい様々な層に広く訴求するイベントだと感じました。皆さんもデータストリーミングに興味があれば、是非参加してみることをお勧めします。

また、本イベントのセッションは動画でアーカイブされており、誰でも見ることができます。非常に多くの有用なセッションがありますので、データストリーミングや Kafka、Flink などのソフトウェアについて知りたいという方は、こちらもチェックしてみてください。

本記事では複数台のマシンを用いて Kafka クラスターを構築し、簡単な動作確認を行います。構築には Ansible を用いて、動作に必要な最低限の設定を行います。使用するバージョンは以下の通りです。

Kafka について

Apache Kafka はストリーミング処理を実現するための OSS です。複数台のマシンで並列分散処理を行わせることができ、高いスケーラビリティ、障害耐性、低いレイテンシといった特徴があります。複数台のマシンでクラスターを構成するため、Ansible を使ってクラスター全体を構築すると楽です。

簡単な動作確認ができる Docker 環境も用意されているのですが、ここでは各マシンに Kafka のバイナリを配置することから始めてクラスターを構築します。Docker 環境で Kafka の動作を試す方法についてはこちらの記事をご覧ください。

Ansible について

Ansible はサーバ構築を自動化するための OSS です。サーバ構築をコード化できるので同時に構築するサーバ数を増やしたりインストールするパッケージを変更したりするのも容易です。コードを見ればサーバの仕様が分かるようにもなります。

サーバ構築のコードを書く際、実行のたびにサーバーの状態が変わってしまうコードになることがあります。そのため何回実行してもサーバの状態が同じになる（このような性質を冪等性と言います）ように気を付ける必要があります。本記事でも冪等性を適宜確認しながら進めます。

今回構築するクラスターの概要

本記事では Broker プロセスが合計5つ、Controller プロセスが合計3つのクラスターを構築します。これらを５台のマシン（Broker とController のプロセスを動かす kafka1~3＋Broker のみの kafka4, 5）で稼働させます。 加えてAnsible のコントロールマシンを立てて Kafka クラスター5台の操作を行います。

Ansible のコントロールマシンと Kafka クラスター5台は ssh で通信できるように設定しておきます。 また dnf によるパッケージインストール時など、root 権限を取得することがあるので構築対象サーバで Ansible を実行するユーザーには sudo 権限を与えておきます。

Ansible ディレクトリ構造

$ tree
.
├── README
├── group_vars
│   └── kafka_cluster.yaml
├── host_vars
│   ├── kafka1.yaml
│   ├── kafka2.yaml
│   ├── kafka3.yaml
│   ├── kafka4.yaml
│   └── kafka5.yaml
├── inventory.ini
├── roles
│   ├── common
│   │   └── templates
│   │       └── kafka_service_template.j2
│   ├── java
│   │   └── tasks
│   │       └── main.yaml
│   ├── kafka_broker
│   │   ├── tasks
│   │   │   └── main.yaml
│   │   └── vars
│   │       └── main.yaml
│   ├── kafka_cluster
│   │   ├── files
│   │   │   └── kafka_2.13-4.0.0.tgz
│   │   └── tasks
│   │       └── main.yaml
│   ├── kafka_controller
│   │   ├── tasks
│   │   │   └── main.yaml
│   │   └── vars
│   │       └── main.yaml
│   ├── terminate_kafka_broker
│   │   └── tasks
│   │       └── main.yaml
│   └── terminate_kafka_controller
│       └── tasks
│           └── main.yaml
├── setup_servers.yaml
└── terminate_servers.yaml

20 directories, 20 files

今回、Kafka の環境準備から設定ファイルの編集、起動 までを行う Playbook（setup_servers.yaml）と Kafka の終了を行う Playbook（terminate_servers.yaml）を作成しました。

playbook 全体の流れ

setup_servers.yaml を以下に示します。

- name: Setup kafka_broker_controller
  hosts: kafka_broker_controller 
  roles:
    - java
    - kafka_cluster
    - kafka_controller
    - kafka_broker

- name: Setup kafka_broker
  hosts: kafka_broker
  roles: 
    - java
    - kafka_cluster
    - kafka_broker

terminate_servers.yaml を以下に示します。

- name: Terminate kafka_broker
  hosts: kafka_broker
  roles: 
    - terminate_kafka_broker

- name: Terminate kafka_broker_controller
  hosts: kafka_broker_controller
  roles:  
    - terminate_kafka_broker
    - terminate_kafka_controller

各タスクは以下の通りです。

各role は以下の通りです。

Controller プロセスは Broker プロセスより先に起動するようにしてあります。Broker プロセスの動作のためにはController が必要だからです。プロセスの終了では逆に Broker プロセスを先に終了させています。

Java のインストール

roles/java/task/main.yaml に Java のインストールを行うタスクを記載しています。

- name: Ensure openjdk21 present
  ansible.builtin.dnf:
    name: java-21-openjdk
    state: present
  become: true

ansible.builtin.dnf では name にパッケージ名、state に実行後どんな状態であるべきかを指定することでパッケージのインストール、アンインストールを行うことができます。state に指定できる状態は以下の通りです。

2回目以降の実行でバージョンが変わらないようにここでは present を使っています。

Kafka バイナリの配置

roles/kafka_cluster/task/main.yaml に Kafka バイナリの配置を行うタスクを記載しています。

- name: Unarchive kafka file
  ansible.builtin.unarchive:
    src: ./roles/kafka_cluster/files/{{kafka_dir}}.tgz
    dest: '{{install_dir}}'
    creates: '{{install_dir}}/{{kafka_dir}}'

ansible.builtin.unarchive では src に Ansible 環境上のアーカイブファイル、dest に構築対象サーバの展開先ディレクトリを指定することでアーカイブファイルの展開ができます。このように設定するとアーカイブファイルを構築対象サーバに送信した後展開処理は構築対象サーバ上で行うという挙動になります。ここではあらかじめ ./roles/kafka_cluster/files/ に置いておいた kafka_2.13-4.0.0.tgz を各サーバで展開しています（変数 kafka_dir と install_dir は group_vars/kafka_cluster.yaml で定義しています）。

構築対象サーバでアーカイブファイルのダウンロード、展開をさせるという方法も考えられます。どのような方法を採用するかは各環境によるでしょう。

また creates に展開後ディレクトリのパスを指定すると、そのディレクトリがすでに存在する場合タスクをスキップさせることができます。
creates がない場合、2回目以降の実行で ansible.builtin.unarchive は展開後のファイルが変更されていないか確認し、変更があれば元の状態に戻すという動きをします。その動きで時間がかからないようにここでは creates を使っていますが、再展開させる必要がある場合は creates を削除するとよいでしょう。

設定

Broker の設定

roles/kafka_broker/task/main.yaml に Broker の設定を行うタスクを記載しています。

- name: Set node.id
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^node.id='
    line: node.id={{node_id_broker}}

- name: Unset controller.quorum.bootstrap.servers
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^controller.quorum.bootstrap.servers='
    line:  '# controller.quorum.bootstrap.servers='

- name: Set controller.quorum.voters 
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^#controller.quorum.voters='
    line:  'controller.quorum.voters=201@{{ hostvars["kafka1"].ansible_host }}:9093,202@{{ hostvars["kafka2"].ansible_host }}:9093,203@{{ hostvars["kafka3"].ansible_host }}:9093'

- name: Set listeners
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^listeners='
    line: listeners=PLAINTEXT://{{ansible_host}}:9092

- name: Unset advertised.listeners
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^advertised.listeners='
    line: '# advertised.listeners='

ansible.builtin.lineinfile では行の置き換えや挿入、削除ができます。ここでは path に指定したファイル内の regexp にマッチした行を line で指定した文字列で置き換えています。

path に指定している path_to_properties ですが、roles/kafka_broker/vars/main.yaml にて kafka_2.13-4.0.0/configs/broker.properties になるように指定しています。つまり kafka_2.13-4.0.0.tgz に同梱されている Broker 用の設定ファイルから設定に必要な行を書き換えています。

regexp にマッチする行がなかった場合は、line に指定した文字列と同じ内容の行があれば何もしない、なければファイル末尾に line の行を挿入するという挙動になります。そのため複数回実行しても同じ内容が挿入され続けることはなく、冪等性が保たれています。

変更している設定値は以下の通りです。ここで Quorum について、静的 Quorum または動的 Quorum が使用できますが今回は静的 Quorum を採用しています。

Controller の設定

roles/kafka_controller/task/main.yaml に Controller の設定を行うタスクを記載しています。

- name: Set node.id
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^node.id='
    line: node.id={{node_id_controller}}

- name: Unset controller.quorum.bootstrap.servers
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^controller.quorum.bootstrap.servers='
    line: '# controller.quorum.bootstrap.servers='

- name: Set controller.quorum.voters 
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^#controller.quorum.voters='
    line:  'controller.quorum.voters=201@{{ hostvars["kafka1"].ansible_host }}:9093,202@{{ hostvars["kafka2"].ansible_host }}:9093,203@{{ hostvars["kafka3"].ansible_host }}:9093'

- name: Set listeners
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^listeners='
    line: listeners=CONTROLLER://{{ansible_host}}:9093

- name: Unset advertised.listeners
  ansible.builtin.lineinfile:
    path: '{{path_to_properties}}'
    state: present
    regexp: '^advertised.listeners='
    line: '# advertised.listeners='

Controller 側の設定もほとんど同じですが、node_id は Controller 用、listeners はリスナー名が CONTROLLER、ポート番号が 9093 になっています。CONTROLLER も認証や暗号化のないリスナーを表しています。

起動

ログディレクトリのフォーマット

roles/kafka_broker/task/main.yaml と roles/kafka_controller/task/main.yaml にログディレクトリのフォーマットを行うタスクを記載しています。内容は同じです。

- name: Format Log Directory
  ansible.builtin.shell:
    cmd: bin/kafka-storage.sh format -t {{kafka_cluster_id}} -c {{path_to_properties}} --ignore-formatted
    chdir: '{{install_dir}}/{{kafka_dir}}/'

ansible.builtin.shell は cmd に指定したコマンドを chdir で指定したディレクトリ上で実行します。コマンドをただ実行するだけのモジュールのため、冪等性の確保等は行いません。Kafka 起動前には Broker と Controller それぞれでログディレクトリのフォーマットが必要ですが、それは kafka_2.13-4.0.0.tgz の bin ディレクトリにある kafka-storage.sh を使って実行します。shell モジュールは冪等性の観点では避けるべきモジュールですが、kafka-storage.sh を使うために今回は使用しています。

kafka-storage.sh format とすればフォーマットを行います。オプションは以下の通りです。

サービスファイルの作成

roles/kafka_broker/task/main.yaml と roles/kafka_controller/task/main.yaml にサービスファイルを作成するタスクを記載しています。内容は同じです。

- name: Copy template of kafka broker service file
  ansible.builtin.template:
    src: ./roles/common/templates/kafka_service_template.j2
    dest: /etc/systemd/system/kafka-broker.service
  become: true

ansible.builtin.template は構築対象サーバにテンプレートファイルをコピーします。その際テンプレートファイル内の変数を変数の値に置き換えた上でコピーします。ここでは src に指定した Ansible サーバ上のテンプレートファイルを dest で指定した構築対象サーバ上のファイルにコピーします。
テンプレートファイルは以下の通りです。

roles/common/templates/kafka_service_template.j2

[Unit]
Description=Kafka server ({{process_role}})
Documentation=https://kafka.apache.org/documentation/

[Service]
Type=simple
Environment="LOG_DIR=/var/log/kafka/{{process_role}}"
ExecStart={{install_dir}}/{{kafka_dir}}/bin/kafka-server-start.sh {{path_to_properties}}
ExecStop={{install_dir}}/{{kafka_dir}}/bin/kafka-server-stop.sh --process-role={{process_role}}

[Install]
WantedBy=multi-user.target

このようなサービスファイルを用いて systemctl で Kafka の起動が行えるようにすることで起動状態の管理を楽にしています。

変数 process_role と path_to_properties は、Broker 用と Controller 用で変わるようになっていて、Broker か Controller かによってサービスファイルの内容が変わるようになっています。

Environment として LOG_DIR を設定していますが、これによってログ出力先（Kafka でやり取りされるメッセージという意味のログではなく、サーバのエラー等を出力するログのこと）を指定できます。

ExecStart では起動コマンドを指定しますが、kafka_2.13-4.0.0.tgz の bin ディレクトリにある kafka-server-start.sh を使用します。kafka-server-start.sh {設定ファイルのパス} と実行することで起動しますが、設定ファイルが Broker のものなら Brokerが、Controller のものなら Controller が起動します。

ExecStop では終了コマンドを指定しますが、kafka_2.13-4.0.0.tgz の bin ディレクトリにある kafka-server-stop.sh を使用します。kafka-server-stop.sh は引数なしだとそのマシン上のすべての Kafka プロセスを終了させてしまうため、--process-role を指定することで指定したプロセスのみを終了させています。

このように Kafka の起動、終了にもスクリプトを使うのですが、systemctl を使うようにすることで ansible.builtin.systemd_service モジュールを使用できるので shell モジュールを避けることができます。

起動

roles/kafka_broker/task/main.yaml に Broker プロセスを起動するタスクを記載しています。

- name: Start Kafka broker
  ansible.builtin.systemd_service:
    name: kafka-broker.service
    state: started
    daemon_reload: true
  become: true

ansible.builtin.systemd_service は name で指定したサービスを state で指定した状態にします。今回は起動した状態にしたいので started としています。

daemon_reload:true としているのは起動前に systemctl daemon-reload を実行し直前でコピーしたサービスファイルを読み込ませるためです。

roles/kafka_controller/tasks/main.yaml に Controller プロセスを起動するタスクを記載しています。

- name: Start Kafka controller
  ansible.builtin.systemd_service:
    name: kafka-controller.service
    state: started
    daemon_reload: true
  become: true

起動させるのが Controller であること以外は Broker の場合と同じです。

終了

roles/terminate_kafka_broker/tasks/main.yaml に Broker プロセスを終了するタスクを記載しています。

- name: Stop kafka broker
  ansible.builtin.systemd_service:
    name: kafka-broker.service
    state: stopped
  become: true

ansible.builtin.systemd_service で state を stopped にすることで Broker プロセスを終了させています。

roles/terminate_kafka_controller/tasks/main.yaml に Controller プロセスを終了するタスクを記載しています。

- name: Stop kafka controller
  ansible.builtin.systemd_service:
    name: kafka-controller.service
    state: stopped
  become: true

対象が Controller になっている点以外は Broker の場合と同じです。

Playbook 実行

実行コマンドは以下の通りです。

$ ansible-playbook -i inventory.ini setup_servers.yaml --ask-become-pass -v

$ ansible-playbook -i inventory.ini terminate_servers.yaml --ask-become-pass -v

動作確認

Kafka クラスターの動作確認としてトピック作成、Produce、Consume を行います。ここでは kafka_2.13-4.0.0.tgz の bin ディレクトリにある kafka-topics.sh、kafka-console-producer.sh、kafka-console-consumer.sh を用います。

• トピックの作成は以下のように行います。

$ ./bin/kafka-topics.sh --bootstrap-server kafka_controller1.example.com:9092 --create --topic test --partitions 5 --replication-factor 5
Created topic test.

kafka-topics.sh でトピックを作成できます。
--bootstrap-server kafka_controller1.example.com:9092
で接続先の Broker を指定するので環境によって変えます。成功すれば Created topic test. と出力されます。

• メッセージの Produce、Consume は以下のように行います。

ターミナルを2つ開いておきます。

Producer 側のターミナルではkafka-console-producer.sh を用います。

$ ./bin/kafka-console-producer.sh --bootstrap-server kafka_controller1.example.com:9092 --topic test
>hoge #プロンプトが表示されたら入力

Consumer 側のターミナルでは kafka-console-consumer.sh を用います。

$ ./bin/kafka-console-consumer.sh --bootstrap-server kafka_controller1.example.com:9092 --topic test --from-beginning
hoge #Producer 側で入力すると表示される

Producer 側で入力した内容が Consumer 側で表示されれば成功です。メッセージの送受信ができることが確認できました。

おわりに

今回は Kafka クラスターの動作に必要な最低限の設定方法をご紹介しました。
同じように Kafka クラスターを構築する方の助けとなれば幸いです。

Kafka Streams について、初心者向けに公式ドキュメントの Core Concepts から基礎的な概念などを解説していきます。

Kafka Streams とは

Kafka Streams は Apache Kafka クラスタ上でストリーム処理アプリケーションを実装するためのクライアント・ライブラリです。Java および Scala のライブラリとして提供されており、簡単にストリーム処理アプリケーションを構築することができます。

Kafka Streams によるストリーム処理の基本の流れとしては、Kafka の Topic にあるデータを入力とし、変換処理を行った後、別の Topic に結果を書き戻す形になります。

Kafka Streams の特徴

Kafka Streams には以下の特徴があります。

• 扱いやすさ
• 構築したアプリケーションは通常の Java アプリケーションとしてパッケージング、デプロイが可能
• ベアメタル、仮想環境、コンテナ、クラウドといった様々な環境にデプロイ可能
• 規模を問わず様々なユースケースに適用可能
• 高機能
• Kafka クラスタの持つ拡張性、弾力性、分散性、耐障害性をアプリケーション側でも利用可能
• Exactly once (データの抜け漏れや重複なく必ず 1 回だけ) の処理セマンティクスをサポート
• 複数レコード間の結合や集約、ウィンドウ処理が可能

ストリーム処理トポロジ

ストリーム処理トポロジとは、ストリーム処理アプリケーションで実行されるデータ処理の流れを定義するものです。トポロジはデータ変換の処理単位をプロセッサ (ノード)、データの流れをストリーム (エッジ) としたグラフで表現されます。

トポロジの末端に位置するプロセッサには特別な名前が付けられています。

• ソースプロセッサ：トポロジの入力であり、Topic からレコードを読み込む
• シンクプロセッサ：トポロジの出力であり、Topic へ処理結果を書き込む

Kafka Streams でストリーム処理アプリケーションを構築する場合は、ライブラリで提供される Processor API か Kafka Streams DSL を用いて、トポロジを定義します。

• Kafka Streams DSL
• Processor API を基盤に構築された宣言型、関数型の DSL
• ステートレス変換 (map、filter) や結合 (join) や集約 (aggregate、count、reduce)、ウィンドウ処理といったステートフル変換を利用可能
• 複雑な変換処理を簡単に記述できるので初心者におすすめ
• Processor API
• 命令型の低レベル API
• ユーザ独自のプロセッサの定義やステートストアとの直接のやりとりが可能
• 柔軟性が高いがより多くのコーディングが必要

ストリームにおける時刻の定義

ストリーム処理においては時刻をモデル化することは重要な概念の 1 つです。ウィンドウなどの操作は時刻に基づいて定義、処理されるからです。

Kafka Streams では以下の時刻の定義が使用されます。

• イベント時刻：イベントまたはデータレコードが発生した時刻
• 処理時刻：イベントまたはデータレコードがストリーム処理アプリケーションによって処理された時刻
• インジェスト時刻：イベントまたはデータレコードが Kafka Broker によって Topic Partition に格納された時刻

ストリームとテーブルの二重性

ストリーム処理における重要な概念としてストリームとテーブルの二重性というものがあります。この二重性とは、本質的にストリームはテーブルとして、テーブルはストリームとして見なせるということです。

• テーブルとしてのストリーム：
  ストリームはテーブルの変更ログと見なすことができます。ストリーム内の各データレコードには、テーブルのステートの変更内容が記載されているため、これを最初から最後まで追うことでテーブルを再構築することができます。
• ストリームとしてのテーブル：
  テーブルは、ストリーム内の各キーに対応するある時点での最新の値のスナップショットと見なすことができます。したがって、異なる時点のテーブル内容を比較することでその変更ログをそのままストリームに変換できます。

Kafka Streams ではこの二重性を KStreams および KTable としてモデル化しています。

ステートフル操作

Kafka Streams ではステートレス操作に加えて、ステートフル操作にも対応しています。ステートフル操作には状態の保存が必要なため、Kafka Streams ではステートストアが提供されます。ステートフル操作の例としては集約、結合、ウィンドウ化があります。

集約

集約操作では 1 つのストリームもしくはテーブルを入力として受け取り、複数のレコードを 1 つに結合してテーブルとして出力します。count や sum といった操作が集約にあたります。

Kafka Streams DSL では入力ストリームは KStream か KTable、出力ストリームは KTable になります。

参考：Kafka Streams/Developer Guide/Streams DSL/aggregationg

結合

結合操作では、データレコードのキーに基づいて 2 つの入力ストリームまたはテーブルをマージして、新しいストリームまたはテーブルを生成します。

Kafka Streams では KStream 同士、KTable 同士、KStream と KTable の結合などが可能ですが、それぞれで可能な結合の種類は異なります。

参考：Kafka Streams/Developer Guide/Streams DSL/Joining

ウィンドウ化

ウィンドウ化では、集約や結合などのステートフル操作において同じキーを持つレコードをグループ化し、ウィンドウと呼ばれる単位に分けて処理を行います。

参考：Kafka Streams/Developer Guide/Streams DSL/Windowing

ステートストア

ステートストアはステートフル操作を行う際のデータの保存やクエリに利用されます。ステートストアは Kafka Streams の各タスクに組み込まれています。

またローカルのステートストアの変更ログは Kafka の専用の Topic に保存されるため、障害時の自動復旧にも対応しています。

参考：Kafka Streams/Architecture/Fault Tolerance

アプリケーションの例

最後に、公式ドキュメントにあるアプリケーションの例を使って Kafka Streams DSL でのアプリケーションの書き方や処理について説明します。

LineSplit

LineSplit は入力文字列をスペースをデリミタとして、単語ごとに区切って出力するアプリケーションです。

public class LineSplit {
    public static void main(String[] args) throws Exception {
        // アプリケーションの設定
        Properties props = new Properties();
        props.put(StreamsConfig.APPLICATION_ID_CONFIG, "streams-linesplit");
        props.put(StreamsConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        props.put(StreamsConfig.DEFAULT_KEY_SERDE_CLASS_CONFIG, Serdes.String().getClass());
        props.put(StreamsConfig.DEFAULT_VALUE_SERDE_CLASS_CONFIG, Serdes.String().getClass());

        // トポロジを定義するためのビルダ
        final StreamsBuilder builder = new StreamsBuilder();

        // 処理内容を DSL で記述
        KStream source = builder.stream("streams-plaintext-input"); // 入力用 Topic を指定
        source.flatMapValues(value -> Arrays.asList(value.split("\\W+"))) // 入力をスペースで区切って分割
              .to("streams-linesplit-output"); // 出力用 Topic に書き込む

        // ビルダからトポロジに変換し、実行
        final Topology topology = builder.build();
        final KafkaStreams streams = new KafkaStreams(topology, props);
        streams.start();
    }
}

WordCount

WordCount は入力文字列の単語ごとに区切ってその出現数を出力するアプリケーションです。この処理は過去の入力文字列のカウント結果を保存しておく必要があるので、ステートストアを利用したステートフルな処理になります。

public class WordCount {
    public static void main(String[] args) throws Exception {
        // アプリケーションの設定
        Properties props = new Properties();
        props.put(StreamsConfig.APPLICATION_ID_CONFIG, "streams-wordcount");
        props.put(StreamsConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        props.put(StreamsConfig.DEFAULT_KEY_SERDE_CLASS_CONFIG, Serdes.String().getClass());
        props.put(StreamsConfig.DEFAULT_VALUE_SERDE_CLASS_CONFIG, Serdes.String().getClass());

        // トポロジを定義するためのビルダ
        final StreamsBuilder builder = new StreamsBuilder();

        // 処理内容を DSL で記述
        KStream source = builder.stream("streams-plaintext-input"); // 入力用 Topic を指定
        source.flatMapValues(value -> Arrays.asList(value.split("\\W+"))) // 入力をスペースで区切って分割
              .groupBy((key, value) -> value) // 単語ごとにグループ化
              .count(Materialized.>as("counts-store")) // 単語をカウントしてステートストアにテーブルとして保存
              .toStream() // テーブルからストリームに変換
              .to("streams-wordcount-output", Produced.with(Serdes.String(), Serdes.Long())); // 出力用 Topic に書き込む

        // ビルダからトポロジに変換し、実行
        final Topology topology = builder.build();
        final KafkaStreams streams = new KafkaStreams(topology, props);
        streams.start();
    }
}

おわりに

この記事では Kafka Streams の基本的な概念について説明しました。

Kafka Streams は難しく見えるかもしれませんが、実際に使ってみると簡単にストリーム処理アプリケーションを実装することができます。みなさんも是非機会があれば Kafka Streams を使ってみてください。

Apache Kafka について

 Kafka の Docker image

docker run -d --name broker apache/kafka:latest

 Docker Compose ファイルについて

├── examples
│   ├── docker-compose-files
│   │   ├── cluster
│   │   │   ├── combined
│   │   │   │   ├── plaintext
│   │   │   │   └── ssl
│   │   │   └── isolated
│   │   │       ├── plaintext
│   │   │       └── ssl
│   │   └── single-node
│   │       ├── file-input
│   │       ├── plaintext
│   │       └── ssl

  controller-1:
    image: ${IMAGE}
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: 'controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@controller-1:9093,2@controller-2:9093,3@controller-3:9093'
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      CLUSTER_ID: '4L6g3nShT-eMCtK--X86sw'
...
  kafka-1:
    image: ${IMAGE}
    ports:
      - 29092:9092
    hostname: kafka-1
    container_name: kafka-1
    environment:
      KAFKA_NODE_ID: 4
      KAFKA_PROCESS_ROLES: 'broker'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@controller-1:9093,2@controller-2:9093,3@controller-3:9093'
      KAFKA_LISTENERS: 'PLAINTEXT://:19092,PLAINTEXT_HOST://:9092'

 実際に動かしてみる

 Kafka クラスタの起動

$ IMAGE=apache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/isolated/plaintext/docker-compose.yml up -d
[+] Running 6/6
 ✔ Container plaintext-controller-3-1  Started                                                                     0.7s
 ✔ Container plaintext-controller-2-1  Started                                                                     0.7s
 ✔ Container plaintext-controller-1-1  Started                                                                     0.7s
 ✔ Container kafka-3                   Started                                                                     1.4s
 ✔ Container kafka-1                   Started                                                                     1.3s
 ✔ Container kafka-2                   Started                                                                     1.4s

$ docker ps
CONTAINER ID   IMAGE                 COMMAND                  CREATED         STATUS         PORTS                                           NAMES
f6c59323b6dc   apache/kafka:latest   "/__cacert_entrypoin…"   4 seconds ago   Up 3 seconds   0.0.0.0:39092->9092/tcp, [::]:39092->9092/tcp   kafka-2
9c8aea6a29e5   apache/kafka:latest   "/__cacert_entrypoin…"   4 seconds ago   Up 3 seconds   0.0.0.0:29092->9092/tcp, [::]:29092->9092/tcp   kafka-1
22124b348942   apache/kafka:latest   "/__cacert_entrypoin…"   4 seconds ago   Up 3 seconds   0.0.0.0:49092->9092/tcp, [::]:49092->9092/tcp   kafka-3
fceba9972dca   apache/kafka:latest   "/__cacert_entrypoin…"   4 seconds ago   Up 4 seconds   9092/tcp                                        plaintext-controller-2-1
9f097d2dffe7   apache/kafka:latest   "/__cacert_entrypoin…"   4 seconds ago   Up 4 seconds   9092/tcp                                        plaintext-controller-3-1
3e326f5b2031   apache/kafka:latest   "/__cacert_entrypoin…"   4 seconds ago   Up 4 seconds   9092/tcp                                        plaintext-controller-1-1

メッセージの送受信

$ bin/kafka-topics.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --create --topic testTopic --partitions 3
...
Created topic testTopic.

$ ./bin/kafka-console-producer.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --topic testTopic
> hoge  # プロンプトが表示されたら入力

 ./bin/kafka-console-consumer.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --topic testTopic --from-beginning
  hoge  # コンソール1で入力すると表示される

デバッガの接続

# Set Debug options if enabled
if [ "x$KAFKA_DEBUG" != "x" ]; then
    # Use default ports
    DEFAULT_JAVA_DEBUG_PORT="5005"
    if [ -z "$JAVA_DEBUG_PORT" ]; then
        JAVA_DEBUG_PORT="$DEFAULT_JAVA_DEBUG_PORT"
    fi
    # Use the defaults if JAVA_DEBUG_OPTS was not set
    DEFAULT_JAVA_DEBUG_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=${DEBUG_SUSPEND_FLAG:-n},address=$JAVA_DEBUG_PORT"
    if [ -z "$JAVA_DEBUG_OPTS" ]; then
        JAVA_DEBUG_OPTS="$DEFAULT_JAVA_DEBUG_OPTS"
    fi
    echo "Enabling Java debug options: $JAVA_DEBUG_OPTS"
    KAFKA_OPTS="$JAVA_DEBUG_OPTS $KAFKA_OPTS"
fi

kafka-1:
  image: ${IMAGE}
  ports:
     - 29092:9092
+      - 25005:5005
   environment:
+      KAFKA_DEBUG: 'y'
+      JAVA_DEBUG_PORT: '*:5005'
...

テストに便利なツール群

kafka-[producer,consumer]-perf-test.sh

$ bin/kafka-producer-perf-test.sh --producer-props bootstrap.servers=localhost:29092,localhost:39092,localhost:49092 --topic testTopic --num-records 1000 --record-size 10 --throughput 10
...
1000 records sent, 99.930049 records/sec (0.00 MB/sec), 3.31 ms avg latency, 263.00 ms max latency, 2 ms 50th, 4 ms 95th, 38 ms 99th, 263 ms 99.9th.

$ bin/kafka-consumer-perf-test.sh --bootstrap-server localhost:29092,localhost:39092,localhost:49092 --topic testTopic --messages 1000
...
start.time, end.time, data.consumed.in.MB, MB.sec, data.consumed.in.nMsg, nMsg.sec, rebalance.time.ms, fetch.time.ms, fetch.MB.sec, fetch.nMsg.sec
2024-12-23 11:15:57:371, 2024-12-23 11:15:57:808, 0.0095, 0.0218, 1000, 2288.3295, 375, 62, 0.1537, 16129.0323

kafka-e2e-latency.sh

•  broker_list: Broker
•  topic: 送信先トピック
•  num_messages: 送信するメッセージ
•  producer_acks: producer が送信の際に利用する Acks の設定
•  message_size_bytes: 送信する1メッセージのサイズ（バイト数）

$./bin/kafka-e2e-latency.sh
USAGE: java org.apache.kafka.tools.EndToEndLatency broker_list topic num_messages producer_acks message_size_bytes [optional] properties_file
$ ./bin/kafka-e2e-latency.sh localhost:29092,localhost:39092,localhost:49092 testTopic 1000 all 10
...
0       142.06386600000002
Avg latency: 3.2986 ms
Percentiles: 50th = 2, 99th = 7, 99.9th = 142

trogdor.sh

まとめ