Kafka の Quota と帯域制御: クライアント単位の利用制限を設計・実装する

マルチテナントや部門横断で Kafka を運用すると、あるクライアントの大量送受信が他を圧迫する問題が起きがちです。Kafka の Quota は、この資源の取り合いを抑え、予測可能なスループットを各クライアントへ配分するための仕組みです。

本記事では、公式ドキュメントに基づくクラスタ安定運用のための Quota 設計・設定・観測方法を、認定試験（CCAAK）で問われる粒度まで具体的に解説します。

Kafka Quota の基本: 何をどう制限するか

Kafka のクライアント Quota は主に 3 種類です。producer_byte_rate（プロデューサの書き込みバイト/秒）、consumer_byte_rate（コンシューマのフェッチバイト/秒）、request_percentage（サーバ処理能力に対する割合的シェア）。超過時はハード拒否ではなく、応答遅延（スロットリング）で制御され、クライアントはレスポンスの throttle_time_ms で遅延を知ることができます。

制限は観測ウィンドウで平滑化され、短時間のバーストは許容しつつ平均レートを守ります（サーバ側の quota.window.num と quota.window.size.seconds で制御）。エンティティは user、client-id、user+client-id（組み合わせ）、およびデフォルト（全体）で指定できます。より具体的なエンティティが優先され、デフォルトは最後に適用されます。

• 対象メトリクス: producer_byte_rate, consumer_byte_rate, request_percentage
• 制御方式: 応答遅延によるソフトスロットリング（throttle_time_ms）
• 平滑化: 観測ウィンドウで平均化し、瞬間バーストを吸収
• 適用単位: user、client-id、user+client-id、default（ワイルドカード）
• 優先度: より具体的な指定が勝つ（user+client-id > user > client-id > default）

スロットリングの流れ（概念図）

代表的な Quota キー（クライアント用）

# クライアント向けに設定可能なダイナミック Quota キー（抜粋）
# - producer_byte_rate: 1秒あたりの送信バイト上限
# - consumer_byte_rate: 1秒あたりの受信（フェッチ）バイト上限
# - request_percentage: サーバ処理能力に対する割合シェア（相対配分）
# いずれも超過時は応答に遅延を入れて調整されます。

エンティティと優先度: user, client-id, 組み合わせ、default

Quota は同時に複数レベルへ設定できます。評価時は最も具体的な一致が優先され、該当がなければより汎用な設定へフォールバックします。たとえば user=alice, client-id=etl の組み合わせがあればそれが使われ、なければ user=alice、さらに無ければ client-id=etl、最後に default へと落ちます。

default の活用で未登録クライアントの暴走を抑えつつ、重要系アプリだけ上限を広げる、といった段階的適用が可能です。

• 優先度（高→低）: user+client-id > user > client-id > default
• default はセーフティネット。まずは default を適切に設定してから個別緩和する
• 命名規約（client.id）を運用に組み込むと可視化と割当が容易

優先度イメージ（擬似マッチ順）

# 擬似コード
if quota.exists(user=u, client=c): use that
elif quota.exists(user=u):        use that
elif quota.exists(client=c):      use that
else:                             use default

設定と検証: kafka-configs.sh と Admin API

クライアント Quota はダイナミック設定としてクラスタに反映できます。kafka-configs.sh（--bootstrap-server 指定）か Admin API を用います。設定は即時に近い形で反映され、ブローカ再起動は不要です。

設定後は describe で確認し、必要に応じて alter/remove を行います。変更はメタデータとしてクラスタに保存され、全ブローカで有効になります。

• 単位はバイト/秒。数値は平均レートで評価される
• 設定はクラスタ全体に適用（特定ブローカ専用ではない）
• 取り消しは --delete-config または該当エンティティ削除で実施

kafka-configs.sh 例（公式ドキュメント系シンタックス）

# client-id 単位
bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --alter --add-config 'producer_byte_rate=1048576,consumer_byte_rate=1048576' \
  --entity-type clients --entity-name etl-writer

# user 単位（SASL Principal 名）
bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --alter --add-config 'producer_byte_rate=2097152' \
  --entity-type users --entity-name alice

# user+client-id（組み合わせ）
bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --alter --add-config 'consumer_byte_rate=524288' \
  --entity-type users --entity-name alice \
  --entity-type clients --entity-name etl-writer

# describe で確認
bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --describe --entity-type clients --entity-name etl-writer

帯域上限の決め方: 実効スループットから逆算する

上限は期待するメッセージサイズ、QPS、圧縮率、ヘッダ等のオーバーヘッドを加味して決めます。初期は需要の80%程度を配り、観測（throttle_time_ms、処理遅延、レイテンシ）を見ながら段階的に調整するのが安全です。

consumer と producer は非対称になり得ます。たとえば大量書き込みでも、読み取りは一部のグループだけ、という構成では consumer_byte_rate を低めに抑えることも合理的です。

• 概算: 上限[bytes/s] ≈ 平均レコードサイズ × QPS × 安全係数
• 観測ウィンドウが短いと揺れやすい。平滑化設定と合わせて設計
• ピーク時の遅延許容値（SLO）に合わせて request_percentage を併用

計算メモ（例）

# 平均 10 KB のレコードを 1500 rps で送る場合（圧縮後同程度と仮定）
# 10 * 1024 * 1500 ≈ 15,360,000 bytes/s ≈ 14.6 MiB/s
# 初期上限: 12–13 MiB/s 程度（観測しながら調整）
# → producer_byte_rate ≈ 13 * 1024 * 1024 = 13631488

観測とトラブルシュート: throttle_time とメトリクス

クライアントは応答ヘッダの throttle_time_ms でスロットリングを検知できます。継続的に非ゼロなら上限に当たっている可能性が高いです。ブローカ側はリクエスト別のスロットル時間やレートに関するメトリクスを公開します（例: リクエスト種別ごとの ThrottleTimeMs）。

スロットルが過大だと、プロデューサはバッファが詰まりレイテンシが増大、コンシューマはフェッチ間隔が伸びてアプリ側遅延やラグ増加につながります。まずは対象エンティティの設定と、default による巻き込みを確認します。

• クライアントログにスロットリングや待機の警告が出る実装が多い
• describe でどのレベル（user / client-id / default）が効いているか確認
• 短い観測ウィンドウだと誤検知が増える。必要に応じて平滑化を調整

JMX/メトリクスの例（名称は環境により異なる）

# 例: リクエスト種別ごとのスロットル
# kafka.network:type=RequestMetrics,name=ThrottleTimeMs,request=Produce
# kafka.network:type=RequestMetrics,name=ThrottleTimeMs,request=FetchConsumer
# ダッシュボードで時系列を可視化し、対象エンティティの設定と突き合わせる

運用パターンと注意点: マルチテナント/レプリケーションとの違い

マルチテナントでは default を堅めに敷き、重要系や夜間バッチにだけ緩和を付与するのが安全です。client.id 命名規約（team-app-purpose など）を統一し、棚卸しを四半期ごとに行うと陳腐化を防げます。

レプリケーショントラフィックのスロットリングはクライアント Quota とは別の設定領域です。パーティション再割当などの運用時に使うもので、アプリケーションクライアントの制御とは混同しないようにしましょう。

• まず default を設定し、想定外の新規クライアントを抑制
• 重要系は user+client-id で必要最小限の緩和を付与
• レプリケーションのスロットリング設定は別物として扱う（再割当時のネットワーク占有を抑える用途）
• CCAAK の観点: 優先度とキー名、スロットリングが遅延で実現される点、観測ウィンドウの概念を押さえる

運用時の棚卸しメモ（擬似手順）

# 1) 実利用の client.id と Principal を収集（メトリクス/ログ）
# 2) default で保護されているか確認
# 3) 重要系だけ user+client-id で緩和
# 4) 90日以上未使用のエントリは削除候補に

問題で確認

よくある質問