Konnect Debuggerを利用して稼働中の本番環境をいろいろ覗いてみる

本エントリはKong Advent Calendar 2025の12/23の投稿です。

はじめに

Kong Gatewayのメトリクスやログを収集し、観測基盤等で可視化したりイレギュラーな状態を確認する事は、健全なトラフィックを維持する上では重要な事です。一般的にはPrometheus形式のメトリクスを取得したりOpen Telemetry形式のSpan情報を可観測性基盤に集約して継続的に観測します。

一方これら情報は、充実した観測環境を準備して初めて有事に利用できるものです。より包括的な情報を取得するにはより多くの情報を保全する必要があり、情報の保全コストやマネージドサービスのコストも運用費を大きく圧迫することになります。

Kong Konnectでは、収集したメトリクスを使った可視化やダッシュボードの機能を提供しています。さらに、ゲートウェイ上のトレース情報を取得する一時的なセッションを開始して、その場で本番環境における振る舞いを確認する事も出来ます。

Konnect Debuggerとは

Konnect Debuggerは、必要な時に短時間のセッションを開始し、ゲートウェイ上のトレース情報を確認出来る機能です。セッション期間中に発生したリクエストに対して、ゲートウェイを通過する際のスパン情報を取得/表示する事が出来ます。Kong Gatewayのバージョンが3.10以上である必要があります。¹

セッションは、一時的とは言っても最長30分指定する事が可能です。ただ長期保存を対象とするものではない為、保全期間は7日間となります。本番環境におけるトラフィック傾向を測るような利用法は向きません。

ユースケース 1 - 本番障害の原因の切り分け

Konnect Debugger最大の特徴は、必要がある時に、実際に現象が発生している環境からトレース情報を取得できる点です。例えば遅延が発生している場合、その遅延がゲートウェイで発生しているのか？それとも接続先サービスか？それがゲートウェイの場合、その原因となるプラグインは何なのか？これら初動調査において重要な原因の切り分けを、今起こっている環境自体で確認する事が出来ます。

例えば上記の場合、ゲートウェイではリクエスト/レスポンスを合わせて4つのプラグインが実行されていますが、プラグインの実行時間の合計は7m秒程度、ゲートウェイ全体でも11m秒程度しか要していません。

スパンの情報を見てみると、接続までに500m秒、実際のサービス側での実行に1.1秒かかっていることが分かります。接続までの時間は物理的な経路や名前解決等にかかる時間であり、解決には抜本的なネットワーク構成の再検討が必要となります。一方サービス側ではコアやインスタンス数の追加や、実装方式の見直しが必要となります。

いずれにせよ、ゲートウェイのみに対するトレース情報ではありますが、比較的短時間で原因の切り分けが可能となります。

ユースケース 2 - プラグインのデバッグ

Kong Gatewayのプラグインは、Global、Service、Route、Consumer、Consumer Group、そしてこれらへの組み合わせに対して適用する事が可能です。非常に柔軟かつ粒度の細かなポリシー適用が可能となりますが、一方想定通り適切にポリシーがかかっているかどうかの判定が難しい場合もあります。

例えば、本来OpenID Connectによる認証が必要なはずなのに、特定のサービスに対してのみアクセスキーを要求されたり、流量制限を超えるリクエストを送るユーザーが存在したりする場合があります。これら問題は、プラグインが入っていないのではなく、何かしらの理由で特定のリクエストに対してプラグインのスコープが上手くフィットしていない事が原因です。

Debuggerでは、具体的にどのプラグインが適用されているかを本番データに対して確認する事が出来ます。テスト環境で想定しているテストデータを用意した再現確認を行う必要もなく、「このユーザーがこのルート経由でこのサービスにアクセスした場合、このプラグインが適用されていない」という非常に明確な原因特定が可能です。

KAiを使ってトラブルシューティング

KAi はKonnectの運用支援エージェントです。エラーが起こっている、もしくは遅延が発生しているルートの特定や、設定における改善点の提示等、様々な運用ニーズに対して支援をしてくれます。

KAiではダイアログを通して探索的に問題の特定をする事が可能ですが、ある程度対象が特定出来た場合にはその対象に対して直ちにトレース分析を指定する事が可能です。

デバッグセッションの提案に対して実行し、セッションが終了するか、対象となるリクエストがキャプチャされた事を確認してセッションを終了すると、自動的にその結果の分析を行います。

ここからさらにプラグインの詳細設定を分析させる事も可能ですが、この分析に利用したセッションはDebuggerに記録が残っているので、自分の目で具体的に何が起こっていたのかを確認する事もできます。

おわりに

Debuggerは稼働環境に対して動的にトレースセッションを開始する機能です。トレース対象はKong Gatewayのみではありますが、ゲートウェイ内の課題や、ゲートウェイと接続サービスの問題の切り分け等、簡単な設定で短時間に多くの情報を抽出/分析する事が可能です。

何かしら想定していない問題が発生した際、いかに迅速に初動調査で問題の特定が出来るかは、プラットフォームの復旧能力に大きく影響を及ぼします。Debuggerを有効に活用して、障害耐性の強いプラットフォーム作りに役立ててください。

1. 厳密にはKong Gateway 3.9.1でも利用可能ですが、この場合は事前にkong.confにてKONG_CLUSTER_RPCとKONG_ACTIVE_TRACINGをOnにしておく必要があります。（これら項目は3.10以降ではデフォルトでOn） ↩