Keycloakを認証基盤として本番運用すると、必ず「何を監視すればいいか」に突き当たります。Quarkus版Keycloakが標準で備えるメトリクス・ヘルスチェック・トレーシングを、管理ポート9000の考え方から監視すべきSLI、キャパシティの見方まで、現場の実務目線で整理します。
認証基盤は「落ちていないか」だけでなく「遅くなっていないか」「捌けているか」まで見えて初めて運用に載ります。Quarkus版Keycloak(現行世代)は、拡張プラグインを追加せず標準機能だけで、メトリクス・ヘルスチェック・分散トレーシングをひととおり出せるようになりました。ここでは新しめのバージョン(26系)を基準に、EMWが実案件で押さえている観点を整理します。バージョンによりオプション名や既定値が変わるため、最終的には利用中のバージョンの公式ドキュメントで確認してください。
01まず管理ポート9000を理解する
Keycloakのメトリクス(/metrics)とヘルス(/health)は、既定でアプリ本体とは別の管理インターフェース(management interface)、ポート9000に出ます。ここが旧WildFly版と大きく違う設計思想で、実務上とても重要です。
- 公開面と管理面を分離できる。エンドユーザーがアクセスする8443(HTTPS)には
/metricsを晒さず、9000はクラスタ内・監視系からのみ到達可能にする、という構成が素直に組めます。 - Ingress/ALB配下では、9000をLoadBalancerに出さず、Prometheusやk8sのkubeletからのみ届くようにするのが定石です。
- 逆に管理ポートを使いたくない場合は主ポートに戻す設定もありますが、露出面が広がるため、エンタープライズでは分離したままを推奨します。
curl http://<pod>:9000/health/readyが通るかを、監視系と同じ経路から確認してください。02メトリクスを有効化する
メトリクスは既定で無効です。--metrics-enabled=true(環境変数 KC_METRICS_ENABLED)で有効化します。エンドポイントは/metricsで、レスポンスはapplication/openmetrics-text、つまりPrometheus(OpenMetrics)テキスト形式です。内部的にはMicrometerを基盤にしており、追加拡張なしでJVM・HTTP・DBプール・キャッシュのメトリクスが出ます。詳細は公式のGaining insights with metricsを参照してください。
代表的に出てくる系列(バージョンで増減あり):
- JVM:GC回数(
base_gc_total)、GC後のヒープ使用率(jvm_memory_usage_after_gc_percent)、ピークスレッド数(jvm_threads_peak_threads)、最大ヒープ(base_memory_maxHeap_bytes)。 - DBコネクションプール(Agroal):アクティブ接続数(
agroal_active_count)など。プール枯渇の早期検知に効きます。 - HTTP:リクエスト件数・処理時間。URI・メソッド・アウトカム別に分解できます。
- 業務系カウンタ:26.2以降、パスワードハッシュ検証回数、ログインフロー、トークンリフレッシュなどKeycloak固有の操作カウンタが出るようになりました(Observability in Keycloak 26.2)。負荷源の特定に有用です。
HTTPやキャッシュのヒストグラム(パーセンタイル算出用)は既定で無効です。レイテンシSLOを測るなら、http-metrics-histograms-enabled=true、あるいはhttp-metrics-slosで区切り(ミリ秒)を明示的に有効化します。ヒストグラムは系列数(カーディナリティ)が増えてPrometheus側の負荷になるため、必要な範囲で入れるのが実務判断です。
02.5可観測性の全体像
03/healthをKubernetesのプローブに正しく割り当てる
ヘルスチェックも既定で無効です。--health-enabled=true(KC_HEALTH_ENABLED)で有効化すると、9000に4つのエンドポイントが出ます。成功で200 OK、失敗で503、本文はJSONです。詳細はTracking instance status with health checksにあります。
/health/started:起動完了判定。startupProbeに割り当て、初回起動の猶予を与えます。/health/live:生存判定。失敗はプロセス再起動を意味するのでlivenessProbeへ。ここを厳しくしすぎると不要な再起動ループを招きます。/health/ready:トラフィック受け入れ可否。readinessProbeへ。DBやクラスタ形成が整うまでtrafficを流さないために使います。/health:全チェックの集約。人間が確認する用途に。
--metrics-enabled=trueも併せて有効化してください。またmTLS運用時はプローブがクライアント証明書を要求されないよう、管理インターフェースのクライアント認証をrequest/none側に寄せる必要があります。liveとreadyの役割分担は事故に直結します。DB一時断でlivenessまで落とすと、全ポッドが同時に再起動して雪崩になります。DB依存はreadinessに寄せ、livenessはプロセス自体の生死だけを見る——これが鉄則です。設計思想はEMWの監視・アラート設計の考え方とも通じます。
04監視すべきSLI(サービスレベル指標)
「全部グラフにする」より、まず少数のSLIに絞るのが運用を楽にします。公式のService Level Indicatorsガイドは、ユーザー体感に直結する3指標を推奨しています。
- 可用性:Prometheusの
upで各ノードのscrape応答を集計。例として月99.9%(≒44分/月の不可用)をSLO目安に。 - レイテンシ:
http_server_requests_seconds_bucket/_countを使い、ログイン系URIのリクエストのうち一定時間内(例:250ms)に完了した割合を測る。ヒストグラム(前述のhttp-metrics-slos等)が前提です。 - エラー率:
http_server_requests_seconds_countをoutcome="SERVER_ERROR"でフィルタし、5xxの比率を測る。認証リクエストで0.1%未満などをSLOに。
これらは負荷の大小に依存せず、ユーザーが感じる品質を直接表すのが利点です。CPU使用率のような「原因側」の指標は、SLIが悪化したときに初めて掘る、という順序が実務的です。26.2以降はPrometheus/Grafana向けのダッシュボードも公式配布されており、パスワード検証・DB接続・HTTPメトリクスを含むので、まずこれを土台に自社要件へ寄せるのが早道です。
05OpenTelemetryトレースで遅延の内訳を割る
「ログインが遅い」が来たとき、内訳がDBかLDAPかInfinispanか——これを切るのがトレースです。トレーシングはビルド時オプションtracing-enabled=trueで有効化し、QuarkusのOTel拡張を通じてスパンを出します。詳細はRoot cause analysis with tracingを参照してください。既定値は実務上そのまま使えます。
- エクスポート先の既定は
http://localhost:4317、プロトコルはgRPC(OTLP)。http/protobufにも切替可能です。同ノードにOTel Collectorを置き、そこからTempo等へ流すのが定番です。 - サービス名の既定は
keycloak。Kubernetes上ではnamespaceやpod名が属性として自動付与されます。 - トレースIDがログにも自動で載るため、ログとトレースの突合が容易です。障害調査の初速が変わります。
- JDBCやInfinispanのトレースは個別にトグルできます。DB由来かキャッシュ由来かを分けたいときに効きます。
tracing-sampler-ratio)の既定は1.0(全件)。本番でこのままだとトレース基盤のコストが跳ねます。公式も本番では小さめの比率を推奨しています。親子スパンの一貫性が欲しければparentbased_traceidratioですが、外部からのトレースヘッダ操作でサンプリングを釣り上げられるDoSリスクがあるため、外向き経路では親ベースの扱いに注意してください。06ログとの組み合わせ・キャパシティの見方
メトリクス・トレースと並んでログも三本柱です。Quarkus版はログハンドラ(console/file/syslog)やフォーマット(JSON構造化ログ含む)を選べます。集約基盤(Loki/Elastic等)に流すならJSON出力にし、前述のトレースID付与と合わせると、メトリクスで異常を掴み→ログで文脈を読み→トレースで内訳を割る、という調査導線が一本で通ります。
キャパシティは、単発の瞬間値ではなく飽和(saturation)に近い指標の伸びで見ます。実務でまず見るのは次のあたりです。
- DBプール:
agroal_active_countが最大接続数に張り付いていないか。ここが天井だとログイン全体が詰まります。プールとDB側max_connectionsの整合はセットで確認します(データベースチューニングも参照)。 - JVMヒープ:
jvm_memory_usage_after_gc_percent。GC後も高止まりならヒープ不足かリーク。GC頻度(base_gc_totalの伸び)と併読します。 - スレッド/HTTP:リクエストレートの伸びに対しレイテンシのパーセンタイルが崩れ始める点が、実効キャパシティの上限サインです。
- キャッシュ:Infinispanのヒット率低下やリモート参照増は、セッション/キャッシュ設計の見直し時期を示します(Infinispanキャッシュチューニング)。
数値の絶対値より「負荷を上げたときにどの指標が先に飽和するか」を負荷試験で把握しておくと、増設判断とHA設計(AWS上のHA構成)が根拠を持てます。EMWでは実案件でこの飽和点の特定から監視・キャパシティ計画までを一体で支援しています。実績は導入事例もご覧ください。
—まとめ
Quarkus版Keycloakは、拡張なしでメトリクス(Micrometer/OpenMetrics)・ヘルス・OpenTelemetryトレースを標準装備します。ポイントは、(1)管理ポート9000で公開面と分離する、(2)live/ready/startedをプローブに正しく割り当てる、(3)まず可用性・レイテンシ・エラー率の少数SLIに絞る、(4)本番はトレースを間引く、(5)キャパシティは飽和指標の伸びで見る——の5点です。いずれもバージョンでオプションが変わるため、公式ドキュメントで最終確認のうえ導入してください。