Monedula

このページは英語から機械翻訳されています。 原文を読む

monedula-sim-link v0.11.0, Apache-2.0

お使いの Kafka クラスターをシミュレーターで開く

実際の Kafka クラスターを可視化するために、monedula-sim-link はそのスナップショットを 1 回取得し、そのクラスターと同じ形の Kafka Simulator を開くリンクを出力します。ブローカー、トピック、パーティションの配置、障害、データ量のサンプル、コンシューマーグループ、トピックの設定まで再現します。リンクを共有することも、AI エージェントに MCP 経由で作らせることもできます。

go install 
go install github.com/monedula-dev/monedula-sim-link/cmd/monedula-sim-link@latest
GitHub Release 
VERSION=0.11.0
curl -L -o monedula-sim-link.tar.gz \
  https://github.com/monedula-dev/monedula-sim-link/releases/download/v${VERSION}/monedula-sim-link_${VERSION}_linux_amd64.tar.gz
tar -xzf monedula-sim-link.tar.gz monedula-sim-link
チュートリアルを始める（英語） GitHub
ターミナル
monedula-sim-link connect --brokers localhost:9092 --topics orders,payments# one snapshot of orders and payments, printed as one linkhttps://monedula.dev/kafka-simulator/playground?scenario=free&actions=…&size=3x6x3x…

ここでは出力されたリンクを短縮しています。

仕組み

  1. 01

    スナップショット connect

    ブローカー、トピック、パーティション、コンシューマーグループ、トピックの設定を一度だけ読み取ります。

  2. 02

    マッピング 名前をマッピング

    ブローカーは broker-1 から broker-N になります。シミュレーターが扱えない名前は変更され、--dry-run で対応表を確認できます。

  3. 03

    バリデーション バリデーション

    リンクは、デコードすると同じアクションに戻り、かつ 2048 文字に収まっていなければなりません（--force が緩めるのは長さだけです）。そうでなければリンクは出力されません。

  4. 04

    出力 URL を出力

    標準出力にリンクを 1 つ出します。同じスナップショットからは常に同じ URL が得られます。

  5. 05

    開く リンクを開く

    プレイグラウンドが、お使いのクラスターと同じ形のフリープレイセッションを開きます。

10
リンク 1 つあたりの最大ブローカー数
6
デフォルトの orders トピック以外の最大トピック数
24
トピックあたりの最大パーティション数
4
最大コンシューマーグループ数
  1. お使いの Kafka クラスター ブローカー、トピック、グループ、設定
  2. connect コマンドライン
    cluster_to_url MCP ツール
  3. 1 つのパイプライン スナップショット、マッピング、バリデーション
  4. プレイグラウンドのリンク Kafka Simulator のフリープレイセッション
CLI と MCP ツールは 1 つのパイプラインを共有しているので、どちらも同じスナップショットから同じリンクを出力します。

クラスターに書き込むことはありません

connect はレコードをプロデュースせず、トピックや設定を作成も変更もせず、コンシューマーグループに参加せず、オフセットもコミットしません。Metadata リクエストは AllowAutoTopicCreation=false を付けて送られるため、トピックを参照してもそれが作成されることは決してありません。クラスター、そのトピック、コンシューマーグループ、トピックの設定を describe できるプリンシパルがあれば十分です。より多くの権限が必要なのは、オプションの --producers だけです。その DescribeProducers リクエストには、選択したトピックに対する Read 権限が必要です。

Kafka クライアントとしての処理全体が 1 つのソースファイル snapshot/kafka.go にまとまっているので、この保証を 1 か所で監査できます。また、Apache Kafka と Confluent Platform のイメージを使った 3 ノード KRaft クラスターに対するエンドツーエンドのテストスイートが、何も変わっていないことを確認します。

読み取り専用の保証（英語）

8 つのリクエストと、オプションの 1 つ
ApiVersionsクライアントのハンドシェイク
Metadataブローカー、トピック、リーダー、レプリカ、同期レプリカ
ListOffsets各パーティションの最も古いオフセットと最新のオフセット
ListGroupsコンシューマーグループ
FindCoordinator各グループのコーディネーターの検索
DescribeGroupsグループの状態とメンバー
OffsetFetchグループがコミットしたオフセット
DescribeConfigs選択したトピックの設定
DescribeProducers--producers を付けた場合のみ。最近書き込んだ冪等プロデューサーとトランザクショナルプロデューサー

リンクが示すもの

リンクは、お使いのクラスターと同じ形をした Kafka Simulator のフリープレイセッションを開きます。1 つのスナップショットからの再構成なので、何が近似なのかを明示しています。実際の正確なオフセット、コントローラー、ラックの配置は引き継がれず、レコードは合成されたものです。

リンクが示すもの（英語）

形
ブローカー数、選択したトピック、その実際のパーティション数とレプリケーションファクター
配置
再割り当て。シミュレーターのデフォルトと異なるパーティションについてのみ
障害
オフラインのブローカーは停止、同期レプリカのリストから外れたブローカーは低速化
データ量
デフォルトでパーティションごとに最大 8 件の、キー付きの合成レコード。それぞれ自分のパーティションに置かれます
グループ
コミット済みのオフセットを持つコンシューマーグループとそのメンバー。ラグは、バックログを消化していくグループとして表現されます
プロデューサー
--producers を付けたときのみ。直近 15 分間に書き込んだ、冪等またはトランザクショナルなプロデューサーを最大 4 つ
設定
cleanup.policy, min.insync.replicas, retention.ms, retention.bytes

ツールは出力する前にリンクをチェックします

プレイグラウンドは不正な形式のエントリを黙って捨てるため、わずかに誤ったリンクは、正しく見えて別のものを表示するセッションを開いてしまいます。

出力前のセルフバリデーション（英語）

2 つのチェック
1アクションログはラウンドトリップできなければなりません。エンコード、デコード、エンコードして同一であること。このチェックは決して無効にできません。
2リンクは 2048 文字以内でなければなりません。--force を付けると、このチェックは警告に格下げされます。

実際のクラスター

TLS、SCRAM、mTLS

平文、TLS、または mutual TLS で接続でき、SASL PLAIN、SCRAM-SHA-256、SCRAM-SHA-512 を使えます。トピックは正確な名前、正規表現、またはその両方で選べます。

シェルの履歴にシークレットが残らないよう、--password よりも環境変数 MONEDULA_SIM_LINK_PASSWORD を使ってください。

保護されたクラスターに接続する方法（英語）

ターミナル 
export MONEDULA_SIM_LINK_PASSWORD='...'
monedula-sim-link connect \
  --brokers broker1.example.com:9093,broker2.example.com:9093 \
  --tls --ca-cert ./cluster-ca.pem \
  --sasl-mechanism scram-sha-512 --username viewer

リンクに含まれる内容をプレビュー

--dry-run は、リンクの前に、サイズのパラメーター、実際のブローカー名、トピック名、グループ名をシミュレーターに表示される名前に対応付ける表、そしてデコードされたアクションのリストを出力します。

手元にクラスターがなくても、demo --dry-run で組み込みのフィクスチャを同じパイプラインに通せます。ここに示した出力は、そのフィクスチャによるものです。

共有する前にリンクをプレビューする（英語）

ターミナル 
monedula-sim-link demo --dry-run
size: 4x3x3xpayments~1~2~1~d~~~~
brokers:
  1 -> broker-1
  2 -> broker-2
  3 -> broker-3
  4 -> broker-4
topics:
  orders -> orders
  payments -> payments
actions (19 entries):
  RP:p1@500
  RG:c1@750
  RA:orders:2:broker-3.broker-1.broker-2@1000
  K:broker-4@1250
  SR:broker-2:1@1500
  ...

AI エージェント向け

同じバイナリに MCP サーバー

monedula-sim-link mcp は stdio 上で Model Context Protocol を提供するので、Claude Code、Claude Desktop、その他の MCP クライアントがリンクを作成できます。4 つのツールは build_playground_url、open_scenario、validate_actions、cluster_to_url で、最後の 1 つは connect と同じ方法で稼働中のクラスターのスナップショットを取ります。

MCP サーバーを使う（英語）

.mcp.json 
{
  "mcpServers": {
    "monedula-sim-link": {
      "command": "monedula-sim-link",
      "args": ["mcp"]
    }
  }
}

インストール

go install 
go install github.com/monedula-dev/monedula-sim-link/cmd/monedula-sim-link@latest
GitHub Release 
VERSION=0.11.0
curl -L -o monedula-sim-link.tar.gz \
  https://github.com/monedula-dev/monedula-sim-link/releases/download/v${VERSION}/monedula-sim-link_${VERSION}_linux_amd64.tar.gz
tar -xzf monedula-sim-link.tar.gz monedula-sim-link

amd64 と arm64 の Linux、macOS、Windows 向けのリリースアーカイブは、チェックサムファイルとともにリリースページにあります。ソースからビルドするには Go 1.25 以降が必要です。次のステップ：シミュレーターで自分のクラスターを見る（英語）。

よくある質問

何が自分のマシンの外に出ますか？
connect は接続先のクラスター以外とは通信せず、最後にリンクを出力します。認証情報は接続を開くためだけに使われ、リンクには含まれません。リンクではブローカーが broker-1 から broker-N と名付けられ、ツールがレコードのキーや値を読むことはありません。リンクに入るのはトポロジーです。ブローカー数、表示するトピックの名前、そのパーティション数、レプリケーションファクター、選択した設定、コンシューマーグループ名、client ID から導いたメンバー名、--producers を付けた場合は最近書き込んだ最大 4 つのプロデューサーの ID、そして障害の情報です。リンクを共有するときは、これらの名前が含まれていると考え、--topics で共有してよいトピックだけを表示してください。詳しくはリンクが示すもの（英語）をご覧ください。
クラスターがシミュレーターで描画できる規模より大きい場合はどうなりますか？
connect は動きの多いトピックとコンシューマーグループを残し、どれを残したかを警告で示します。まず --topics で指定したトピック、次に複製不足またはオフラインのパーティション、コンシューマーラグ、読み取るグループがあるトピック、そしてラグが最も大きいグループです。ブローカーが 10 台、またはトピックあたりのパーティションが 24 個を超えると、失敗してリンクを出力しません。--clamp を渡すと、それらを決定的に切り詰めます。詳しくは大規模クラスターの扱い（英語）をご覧ください。
仕事で使えますか？
はい、Apache-2.0 では、ライセンスと告知を残す限り、商用利用、改変、再配布が認められています。Apache Kafka は Apache Software Foundation の商標です。monedula-sim-link は Kafka クラスターと連携する独立したプロジェクトであり、ASF との提携関係はなく、ASF による承認や後援も受けていません。

サポート

開発者自身によるサポート

大規模な環境で monedula-sim-link を動かすために、設計から日々の運用まで私たちがお手伝いできます。

お問い合わせ

所属
Monedula Flock

同じチームによる、Apache Kafka のための無料ツールがほかにもあります。Flock について