confluent-tuning-advisor

Confluent Tuning Advisor

ワークロードの優先事項（レイテンシー、スループット、可用性、耐久性）を、プラットフォームに適した具体的な推奨事項に変換します。変更する Kafka 設定、変更前後の値、変更理由、トレードオフ、および管理者が変更後に検証する方法を示します。対象はConfluent CloudとConfluent Platformのみです。Kafka のみが対象です。Flink（Flink SQL ジョブのチューニングを含む）は対象外です。説明の「実行してはいけない」条項を参照してください。

これら4つの優先事項は互いに独立していません。すべての推奨事項には、少なくとも1つの別の軸とのトレードオフが伴います。このスキルの主な役割は、都合のよい解決策があるかのように装うのではなく、そのトレードオフを明確にすることです。

助言のみ — このスキルは一切変更を加えません。 設定や実行時の状態を（読み取り専用で）調査し、変更を提案することはできます。変更の適用、書き込み／生成操作の実行、またはブローカー、トピック、クライアントへのその他の変更は決して行いません。推奨事項を確認して適用する責任は、管理者または開発者のみにあります。推奨と実行は厳密に分けてください。提案する変更を提示し、適用の許可を求めず、適用せず、変更が行われたと述べたり示唆したりしないでください。このスキルには実行可能なスクリプトは含まれていません。実行するのは、Confluent CLI、MCP サーバー、Kafka REST v3／REST Proxy v3、Cloud Metrics API を使用した、設定やメトリクスの読み取り専用の調査のみです。

どのファイルをいつ読むか

状況	参照先
ユーザーが Confluent Cloud を対象としている	references/confluent-cloud.md
ユーザーが Confluent Platform（セルフマネージド）を対象としている	references/confluent-platform.md
優先事項ごとの設定項目の検索（プロデューサー／コンシューマー／トピック／ブローカー）	references/tuning-parameters.md
Platformでの変更を検証する場合、または変更の効果を証明するブローカー JMX メトリクスを選ぶ場合（ステップ7）	references/monitoring.md
Cloudでの変更を検証する場合、または変更の効果を証明するメトリクスを選ぶ場合（ステップ7）	サーバー側のメトリクスは references/confluent-cloud.md を参照してください。クライアントメトリクスのセクションのみを使う場合は references/monitoring.md を参照してください

これらを最初にすべて読む必要はありません。その時点のステップで必要なものだけを読み込んでください。

基本ワークフロー

1. ワークロードと優先事項を把握する
2. プラットフォーム（Cloud または Platform）を特定し、該当するリファレンスファイルを読む
3. 現在の有効な設定をベースラインとして（読み取り専用で）調査する
4. references/tuning-parameters.md で推奨事項を確認する
5. 根拠、影響、リスク、前提条件、検証手順とともに、変更案を提示する（適用を求めず、適用もしない）
6. 管理者に引き継ぎ、管理者自身に確認と適用を任せる
7. 管理者が変更を適用した後に確認できる検証手順を伝える
8. 目標がまだ達成されていない場合は、推奨事項を見直す

---

ステップ 1：ワークロードと優先事項を把握する

次の項目をまとめて確認します。

1. 最優先事項 — 次のいずれか 1 つだけです：レイテンシ、スループット、可用性、耐久性。 ユーザーが副次的な優先事項も挙げる場合があります。その場合は、優先事項が競合したときは常に最優先事項が優先されることを明確にします。
2. 「良好」とはどのような状態かを数値化する — 例：「プロデューサーからコンシューマーまでの p99 レイテンシを 20ms 未満にする」、 「200 MB/s を維持する」、「1 つの AZ を失ってもダウンタイムをゼロにする」、「ブローカーが書き込み中に停止してもデータ損失をゼロにする」。曖昧な目標（「速くする」など）は受け入れず、数値を尋ねます。
3. ワークロードの特性 — おおよそのメッセージサイズ、想定されるメッセージ数/秒、プロデューサーとコンシューマーの数、 メッセージがトランザクション対応か／厳密に 1 回だけ処理されるか、既存の場合は現在のトピック名とパーティション数。
4. 既存のワークロードの場合、現在実際に問題となっていること — 推測より具体的な症状を優先します。

ユーザーが重要な軸だけを述べ、それ以外の情報を示さない場合は、参照ファイルに触れる前に上記の聞き取りを進めます。推奨事項は軸の名称だけでなく、数値化された目標に基づくためです。

ステップ 2：プラットフォームを特定する

このワークロードがどのプラットフォームで実行されているかを尋ねます：Confluent Cloud または Confluent Platform （セルフマネージド）。このスキルは WarpStream やアンマネージドの Apache Kafka を対象としていません。ユーザーがそのいずれかを挙げた場合は、その旨を伝えて終了します。また、Kafka Connect（コネクターまたはワーカーのチューニング）も対象外です。コネクターまたは Connect ワーカーに関する依頼の場合は、対象外であることを伝えて終了します。

Flink に関する依頼は即時終了します。 依頼に Flink が少しでも含まれる場合 — Flink SQL ジョブ、Flink パイプライン、並列度、チェックポイント、状態バックエンド、遅延または低速な Flink ステートメント、UDF など — このスキルは適用されません。対象外であることを伝え、ユーザーを confluent-cloud-flink-sql（Flink SQL）または flink-udf（Flink UDF）に案内して、そこで終了します。ワークフローを進めたり、代替案や埋め合わせとして基盤となる Kafka のトピック／プロデューサー／コンシューマーのチューニングを提案したりしないでください。（ユーザーが後日、Flink のチューニング依頼を含まない、Kafka トピックまたはクライアント設定だけに関する依頼をしてきた場合は、新たな対象範囲内の依頼として扱います。）

対象外の依頼を引き継ぐ場合は、すべて同じルールに従います。 このスキルが対応を断る場合は常に、適切なスキル名を示して終了します — 新しいクライアントアプリケーションコード（developing-kafka-java-client、developing-kafka-python-client）、Kafka Streams（kafka-streams-programming）、Kafka Connect、CDC/Tableflow（confluent-cloud-cdc-tableflow）、WarpStream、Apache Kafka OSS など。引き継ぎ時にチューニングの推奨事項、デフォルト値、「事前に決めておくとよい」設定に関するアドバイスを付け加えないでください。対応を断りながら acks、パーティション数、その他の設定を提案するのもチューニングの推奨事項に当たり、それこそが引き継ぎを不適切なものにします。対応を断ることだけが回答です。

ここで該当する参照ファイルを読みます。

• Confluent Cloud → references/confluent-cloud.md — クラスター階層の制限、Confluent が管理するものと設定可能なもの、クォータの仕組み。
• Confluent Platform → references/confluent-platform.md — ブローカーレベルの設定項目、ラック認識、テールレイテンシに影響する JVM／OS レベルの要因。

ステップ 3：現在の設定をベースラインとして確認する（読み取り専用）

推奨を提示する前に、現在実際に設定されている内容を記録します。差分として表現した推奨のほうが、絶対値よりも把握しやすく、確認もしやすくなります。これは読み取り専用の確認（describeConfigs）であり、変更は行いません。環境にすでにある方法を使用してください。

• CLI：現在の Confluent CLI ドキュメントを参照し、対象プラットフォームとインストール済み CLI バージョンに対応する、読み取り専用のトピック詳細確認操作を探してください。
• MCP ツール：設定済みの Confluent MCP サーバーから、読み取り専用のトピック詳細確認ツールまたはトピック設定一覧表示ツールを見つけてください。利用できる場合は、検出にこの方法を優先してください。
• REST：適切なものとして、現在の Confluent Cloud Kafka REST v3 API reference または Confluent Platform REST Proxy v3 API reference にある読み取り専用のトピック設定一覧表示操作を使用してください。Kafka のブートストラップアドレスは HTTP エンドポイントではありません。クラスターのアドバタイズ済み REST エンドポイントを使用してください。

作成予定のトピックがまだ存在しない場合、詳細確認を試みないでください。そのトピックの設定は「未作成」と記録し、サイズを決めるために必要なクラスターのデフォルト値と容量制限のみを確認してください。ステップ 5 では、そのトピックについて現在値 → 推奨値の差分ではなく、初期値の案を提示してください。

ブローカー／クラスター単位のベースライン（Platform のみ。Cloud では公開されていません）については、CLI／REST でブローカーリソースに対して describeConfigs と同等の操作を行います。ステップ 5 で現在値 → 推奨値の明確な差分を提示できるよう、変更を提案する値を記録してください。

必要なクライアントまたはブローカーのベースラインを確認できない場合、またはユーザーから提供されていない場合、記憶しているデフォルト値を現在の状態として推測して提示しないでください。不足している実効値を尋ねるか、ベースラインが得られるまで、診断の案内と、候補として明示した変更案の提示にとどめてください。

推奨に記載するすべての値には、次の 2 つのルールを適用します。

• 主張の根拠を示すこと。 現在値、プラットフォームの機能、クラスター種別の動作に関する記述はすべて、確認済みの結果、最新のドキュメント、またはユーザー自身の発言に基づいている必要があります。いずれにも基づいていない場合、それは事実ではありません。断定せず、前提条件の未解決事項として提示してください。
• 読み取り専用の結果を尊重すること。 確認結果でキーが読み取り専用（is_read_only=true）と報告された場合、変更、削除、上書きを提案しないでください。プラットフォームによって管理されていることを伝え、次に進んでください。

ステップ 4：推奨事項を調べる

references/tuning-parameters.md を開き、ワークロードに関連する各設定対象（プロデューサー、コンシューマー、トピック／レプリケーション、ブローカー／クラスター）の行を確認します。優先度ごとの推奨値と、その理由が一文で記載されています。すべての行をそのまま写すのではなく、ステップ 1 で定量化した目標と照らし合わせて調整してください。たとえば、「可用性」を優先する場合でも、利用可能なブローカーが 2 台しかなければ、min.insync.replicas に安全に設定できる値は変わります。クラスターで維持できない値を推奨するのではなく、その点を明確に説明してください。

ステップ 5：推奨事項を提示する

実行を依頼するのではなく、推奨事項を提示してください。「適用しますか？」とは尋ねず、いかなる変更も適用しないでください。実行するかどうかは管理者が決定します。次の形式を使用してください。

Tuning recommendation — priority: <latency|throughput|availability|durability>
Target: <the quantified goal from Step 1>
Platform: <Confluent Cloud | Confluent Platform>

Proposed changes (current → recommended):
  <config.key>            <current value>  →  <recommended value>   (why: <one line>)
  <config.key>            <current value>  →  <recommended value>   (why: <one line>)
  ...

For `replication.factor` changes, follow the topic-creation and reassignment guidance in
[references/tuning-parameters.md](references/tuning-parameters.md).
Never recommend deleting and recreating an existing topic solely to change its replication factor;
on Confluent Platform, preserve the topic and use an explicit replica reassignment after confirming
broker and rack capacity.

Expected impact: <what should measurably improve, tied to the Step 1 target>
Trade-off / risk: <what gets worse on another axis, stated plainly — e.g.
  "min.insync.replicas 3→2 improves availability during a single-broker outage but
  means a write can be acknowledged with one fewer copy durably stored">
Prerequisites: <anything that must be true/checked first — e.g. broker.rack configured,
  cluster tier supports multi-zone, enough brokers to sustain the new min.insync.replicas>

How to apply (for the administrator to run — this skill does not run these):
  1. <description>
     Command/tool: <operation and current documentation link; include exact syntax only after
       verifying it against the installed CLI, discovered MCP tool, or current API documentation>
  2. ...

Validation (Step 7) — how the administrator confirms it worked after applying:
  Server-side metric: <a metric name confirmed available on this platform — a Platform JMX MBean,
    or a Cloud metric returned by live descriptor discovery. When the target is Cloud and
    descriptors are unavailable, name no server-side metric here and emit exactly this line:
    Server-side metric validation: pending descriptor access>
  Client/application signal: <an accessible client metric or application-level SLI>
  Benchmark (optional, administrator-run): <the before/after measurement from Step 7>

「適用方法」のコマンドは、管理者が自身の権限で実行するための参考情報として提示してください。このスキルが実行するものとして扱ったり、実行許可を求める表現にしたりしてはいけません。ユーザーが異議を唱えたり、別のバランスを求めたりした場合は、推奨内容を修正して再提示してください。

ステップ 6：実行の引き継ぎ（適用するのは管理者であり、このスキルではありません）

このスキルは変更を適用しません。 推奨事項を提示した時点で終了します。管理者または開発者が内容を確認し、自身の権限に基づいて、すでに使用している任意のツールを使って変更を適用します。ステップ 5 の「適用方法」ブロックには、推測なしに内容を確認して実行できるよう、実行する操作が正確に記載されています。次のいずれかを使用します。

• MCP ツール — Confluent MCP サーバーが公開している場合は、検出されたトピック設定の更新ツール。
• CLI — 対象プラットフォームおよびインストール済み CLI バージョンに対応する、現在文書化されているトピック設定の更新操作。
• REST / Admin API — ブローカーレベルの変更には、現在の Confluent Platform のドキュメントを使用してください。Cloud ではブローカー設定は公開されていません。

変更によってサービスに影響が出る場合（例：ブローカーの再起動、またはクラスター内のすべてのトピックに影響するブローカーレベルのデフォルト設定）は、その旨を伝え、管理者への推奨事項として、ブローカーを 1 台ずつ変更し、ブローカーごとにクラスターの健全性を確認するよう勧めてください。このスキルが実行する操作として示してはいけません。これらの操作は決して自分で実行せず、変更が「適用された」と決して述べないでください。管理者が変更を適用した後に管理者自身が確認できる内容について述べることは差し支えありません。

ステップ 7：管理者に検証手順を伝える

変更によって対象の指標が実際に改善したことを確認できる方法を管理者に伝えます。設定が反映されたと信じ込ませてはいけません。以下は、適用後に管理者自身が実行する手順です。このスキルでは実行しません（ベンチマークはレコードを生成・消費する書き込み／変更操作であり、助言のみを行うこのスキルの範囲外です）。

推奨する検証は、次の 2 つの要素で構成されます。

1. 監視し、アラートを設定しておく指標。 references/monitoring.md を参照し、優先度に応じて、変更が有効だったことを示す具体的な指標を挙げます。たとえば、可用性／耐久性には UnderReplicatedPartitions、レイテンシにはリクエストレイテンシの内訳、コンシューマーのスループットには records-lag-max を使います。Confluent Platform ではこれらは JMX MBean です。Confluent Cloud では、すべてのブローカー JMX MBean が公開されていると仮定せず、利用可能な Metrics API の相当する指標とクライアント指標を使います。Platform の JMX 名を示す場合は Platform 専用と明記し、現在の対象が Platform であっても、この Cloud との違いを明示してください。これは読み取り専用の検証であり、主たる検証方法です。

Cloud の検証における禁止事項： Confluent Cloud の検証には、管理対象ブローカーの停止、再起動、強制終了、隔離など、障害を注入する手順を決して含めてはいけません。管理者向けの手順、任意のテスト、仮定上の手順、将来の推奨のいずれとしても記載しないでください。回答にそのような手順を記述してはいけません。検証には、文書化されたクラスタタイプの保証、有効なトピックとプロデューサーの設定、アクセス可能なクライアント／アプリケーションのシグナル、および Metrics API のディスクリプターを実際に検索して確認したサーバー側指標のみを使ってください。検索でまったく同じ名前が返された場合を除き、Platform の JMX MBean 名を Cloud の指標名として流用してはいけません。クラスタタイプのメタデータ、Metrics API の認証情報、またはディスクリプターを利用できない場合は、その検証項目を保留中と明記してください。ブローカーへの操作や、推測した指標名で代用してはいけません。

2. 管理者自身が実行する任意の変更前／変更後ベンチマーク。 数値で変更前／変更後を比較したい場合は、管理者自身のツールを使って実行するよう推奨します。このスキルにはベンチマークのツールは含まれておらず、実行もしません（ベンチマークはレコードを生成・消費する書き込み操作であり、管理者が実施するものです）。すでに利用している以下のツールを案内してください。

   • kafka-producer-perf-test ／ kafka-consumer-perf-test（Kafka／Confluent Platform に同梱されています）。
   • または、ステージングトピックに対する既存の負荷テストハーネス。

   適用前と適用後にそれぞれ一度実行し、達成スループットとp99（テール）レイテンシを比較するよう推奨します。平均値だけでは不十分です。SLA はテールを基準に定められます。エンドツーエンドのレイテンシは、プロデューサーの send() からコンシューマーの poll() までを測定します。

結果はステップ 1 の目標に照らして説明し、ステップ 5 のトレードオフも再度明示して、何が改善し、何が悪化すると予想されるかを管理者が把握できるようにします。万能な設定はありません。証明となるのは推奨設定の表ではなく、管理者自身が行う変更前／変更後の測定です。

ステップ 8：推奨内容を見直す

管理者が推奨設定を適用して検証した後も目標が達成されていない場合は、新しいベースラインを再確認し（ステップ 3）、推奨内容を調整します（ステップ 4）。一度の調整だけでは十分でない主な理由には、パーティション数がボトルネックになっている（スループット）、新しいブローカー／トピック設定に合わせてクライアント側のバッチ処理設定も変更されていない、またはワークロードが Kafka 以外の要因（シリアライズのコスト、ネットワーク経路、下流コンシューマーの処理時間）に制約されている、といったものがあります。その場合は、効果のない Kafka の設定項目を推奨し続けず、その旨を伝えてください。

---

セキュリティとデータの取り扱い

• cat、Read、head、grep、その他のツールを使って.envファイルの内容を読み取らないでください。 変数は名前だけを参照し（例：$BOOTSTRAP_SERVERS）、値を出力せずに test -n "$VAR"で存在を確認してください。
• 認証情報を誤ってコミットしないよう、.envを.gitignoreに追加してください。
• このスキルの評価用プロンプト、フィクスチャ、サンプルデータには、合成値のみを使用します — example.com／.exampleの名前、架空のクラスター／トピックIDを使用します。このスキルの例を応用する際に、実際の顧客 識別子、ホスト名、認証情報に置き換えないでください。
• 助言のみで、書き込みは行いません。 このスキルは、変更の適用、書き込み／生成／変更操作の実行、ブローカー、トピック、クライアントの変更を決して行ってはなりません。「安全」な適用や「ドライランしてから確認」する適用であっても、またユーザーが実行を指示した場合であっても同様です。このスキルには実行可能なスクリプトは含まれていません。実行するのは、Confluent CLI、MCP サーバー、Kafka REST v3／REST Proxy v3 API（トピック設定の読み取り）、Cloud Metrics API／Platform JMX（メトリクスの読み取り）を使った読み取り専用の設定／メトリクス確認だけです。ベンチマークではレコードを生成／消費するため、実行するのは管理者であり、このスキルではありません。提案はしますが、実行はしません。適用の許可を求めず、変更を適用したと主張したり、適用したかのように示唆したりしないでください。変更の実行を求められた場合は、適用は管理者の責任であると改めて伝え、管理者が実行するための正確な操作を提示してください。

参照ファイル

• references/confluent-cloud.md — クラスターティアのトレードオフ、Confluent Cloud が管理するものと公開するもの、クォータの仕組み、マルチゾーン、Cluster Linking によるDR（RPO／RTOの実情）。
• references/confluent-platform.md — ブローカーレベルの設定、ラック認識、ハードウェア／OS／JVMのベースライン（ヒープ、ページキャッシュ、GC、ディスク、ファイル記述子）、マルチデータセンターDR。
• references/tuning-parameters.md — プロデューサー／コンシューマー／トピック／ブローカーの設定マトリックス（設定ごとに1行、優先度ごとに1列）、パーティションのサイジング、ベンチマーク／サービス目標の手法。
• references/monitoring.md — チューニング変更の効果を示すJMX／Metrics APIのメトリクス。優先度別にまとめ、常にアラートを設定するベースラインも記載しています。