キーサーバーのメトリクス

gokeyless キーサーバーは Prometheus ↗ のメトリクスエンドポイントを公開します。署名の性能、エラー率、接続の健全性、証明書の期限切れを監視できます。このエンドポイントは OpenTelemetry Collector の Prometheus レシーバーでもスクレイプできるため、OpenTelemetry 対応の任意のバックエンドへメトリクスを渡せます。

デフォルトでは、メトリクスは次の URL で提供されます。

http://<host>:2406/metrics

ポートは、設定ファイルの metrics_port、--metrics-port フラグ、または KEYLESS_METRICS_PORT 環境変数で変更できます。

このエンドポイントが提供するのは /metrics だけです。/health や /debug などの追加の HTTP エンドポイントはありません。

ヒストグラムメトリクスは、すべて同じバケット設定を使います。100 マイクロ秒から始まり、各ステップで 2 倍になる指数バケットが 15 個あり、およそ 1.64 秒まで続きます。最後に +Inf バケットがあります。

Type: Counter
Labels: opcode

確立済み接続で受け取ったリクエストを、結果に関係なくすべて数えます。処理を始める前に、リクエストごとに 1 回インクリメントします。

opcode ラベルには、gokeyless プロトコルの定数名をそのまま使います。

Type: Histogram
Labels: type, error

処理開始から応答生成までの、1 回の操作の実行時間を測ります。PKCS#11 HSM を使う操作では、プールからのセッション待ち時間と、HSM 上の暗号操作時間の両方が含まれます。

このメトリクスには、リクエストが接続セマフォのスロットを待つ時間は含まれません。その時間は keyless_request_total_duration_per_opcode で記録します。

このラベルでは、opcode をより粗いカテゴリにまとめます。

成功したリクエストの値は no error です。それ以外は失敗した操作です。

Type: Histogram
Labels: type、error（keyless_request_exec_duration_per_opcode と同じ値）

リクエストパケットをワイヤから読み取ってから、応答バイトをクライアントへ書き戻すまでの、リクエスト全体の所要時間を測ります。

total_duration = exec_duration + response_write_time

両方のタイムスタンプは、接続セマフォを取得したあとに記録します。そのため、セマフォのキュー待ち時間はどちらのヒストグラムにも含まれません。通常の負荷では、total duration と exec duration はほぼ同じです。差が広がっている場合は、クライアントへの書き戻しが遅いことを示します。たとえば、キーサーバーと Cloudflare エッジの間のネットワークバックプレッシャーです。

Type: Histogram
Labels: なし

キーストアが各リクエストの秘密鍵を探して返すまでの時間を測ります。キーは SKI、SNI、サーバー IP です。

• ファイルベースのキーストアではマップ検索であり、通常は 1 ミリ秒未満です。
• PKCS#11 または HSM キーストアでは、鍵参照がメモリにキャッシュされていない場合、HSM へのネットワーク往復が含まれることがあります。

このメトリクスは、署名と復号の操作すべてで記録します。対象は OpRSADecrypt、すべての OpRSASign*、すべての OpRSAPSSSign*、すべての OpECDSASign*、および OpEd25519Sign です。

OpPing、OpSeal、OpUnseal、OpRPC、OpCustom では記録しません。これらは秘密鍵の検索が不要です。

Type: Counter
Labels: なし

接続レベルのトランスポート障害を数えます。このメトリクスはネットワーク層または TLS 層の問題を表します。署名エラーや鍵の検索失敗は数えません。それらは duration ヒストグラムの error ラベルで報告します。

Type: Gauge
Labels: source、serial_no、cn、hostnames、ca、server、client

キーサーバーが読み込んだ各証明書の有効期限（NotAfter）を Unix タイムスタンプで報告します。証明書ごとに 1 つの時系列を出力します。

このメトリクスは次のタイミングで更新されます。

• 起動時。サーバー認証証明書（auth_cert）と Cloudflare CA 証明書（cloudflare_ca_cert）。
• 受信 TLS 接続が成功するたび。接続クライアントが提示したピア証明書。

sum by (opcode) (rate(keyless_requests[1m]))

sum by (error) (
  rate(keyless_request_exec_duration_per_opcode_count{error!="no error"}[5m])
)

histogram_quantile(
  0.99,
  rate(keyless_request_exec_duration_per_opcode_bucket{type="rsa"}[5m])
)

値が 10 秒に近づいている場合は、PKCS#11 セッションプールの枯渇を示します。セッションプールサイズの増やし方は、スケーリングとベンチマーク と HSM のドキュメントを参照してください。

histogram_quantile(0.99, rate(keyless_key_load_duration_bucket[5m]))

exec duration に対応する急増がなく、ここだけが急増している場合は、キーストアの検索自体が遅い可能性があります。ディスク I/O の問題や、PKCS#11 オブジェクト列挙の遅延が考えられます。

rate(keyless_failed_connection_total[5m])

0 以外の値が続く場合は、Cloudflare ネットワークとキーサーバーの間にネットワークまたは TLS の問題があります。

(certificate_expiration_timestamp_seconds - time()) / 86400 < 30