密钥服务器指标

gokeyless key server 暴露一个 Prometheus ↗ 指标端点，您可以用它监控签名性能、错误率、连接健康状况和证书过期时间。该端点也可由 OpenTelemetry Collector Prometheus receiver 抓取，使指标可用于任何兼容 OpenTelemetry 的后端。

指标端点

默认情况下，指标在以下地址提供：

http://<host>:2406/metrics

端口可通过配置文件中的 metrics_port 键、--metrics-port 标志或 KEYLESS_METRICS_PORT 环境变量进行配置。

该端点仅提供 /metrics。没有 /health 或 /debug 等其他 HTTP 端点。

直方图桶

所有直方图指标共享相同的桶配置：15 个指数桶，从 100 微秒开始，每步翻倍，最大约 1.64 秒，外加一个最终的 +Inf 桶。

桶	上限
1	100 µs
2	200 µs
3	400 µs
4	800 µs
5	1.6 ms
6	3.2 ms
7	6.4 ms
8	12.8 ms
9	25.6 ms
10	51.2 ms
11	102 ms
12	205 ms
13	410 ms
14	819 ms
15	~1.64 s
+Inf	高于 ~1.64 s 的任何值

指标参考

`keyless_requests`

类型： Counter
标签： opcode

统计通过已建立连接收到的每个传入请求，无论结果如何。在处理开始前每个请求递增一次。

opcode 标签使用 gokeyless 协议中的完整常量名称。

RSA 操作

`opcode` 标签	线路值	描述
`OpRSADecrypt`	`0x01`	RSA 原始解密 — 用于 TLS RSA 密钥交换（在 TLS 1.3 中已弃用）
`OpRSASignMD5SHA1`	`0x02`	对 MD5+SHA1 组合哈希的 RSA PKCS#1 v1.5 签名 — TLS 1.0/1.1 握手
`OpRSASignSHA1`	`0x03`	对 SHA1 的 RSA PKCS#1 v1.5 签名
`OpRSASignSHA224`	`0x04`	对 SHA224 的 RSA PKCS#1 v1.5 签名
`OpRSASignSHA256`	`0x05`	对 SHA256 的 RSA PKCS#1 v1.5 签名
`OpRSASignSHA384`	`0x06`	对 SHA384 的 RSA PKCS#1 v1.5 签名
`OpRSASignSHA512`	`0x07`	对 SHA512 的 RSA PKCS#1 v1.5 签名
`OpRSAPSSSignSHA256`	`0x35`	对 SHA256 的 RSASSA-PSS 签名 — TLS 1.3 中的主要 RSA 操作
`OpRSAPSSSignSHA384`	`0x36`	对 SHA384 的 RSASSA-PSS 签名
`OpRSAPSSSignSHA512`	`0x37`	对 SHA512 的 RSASSA-PSS 签名

ECDSA 操作

`opcode` 标签	线路值	描述
`OpECDSASignMD5SHA1`	`0x12`	对 MD5+SHA1 组合哈希的 ECDSA 签名
`OpECDSASignSHA1`	`0x13`	对 SHA1 的 ECDSA 签名
`OpECDSASignSHA224`	`0x14`	对 SHA224 的 ECDSA 签名
`OpECDSASignSHA256`	`0x15`	对 SHA256 的 ECDSA 签名 — TLS 1.2 和 TLS 1.3 中最常见
`OpECDSASignSHA384`	`0x16`	对 SHA384 的 ECDSA 签名
`OpECDSASignSHA512`	`0x17`	对 SHA512 的 ECDSA 签名

其他签名

`opcode` 标签	线路值	描述
`OpEd25519Sign`	`0x18`	对任意长度载荷的 Ed25519 签名（非预哈希摘要）

密封和基础设施操作

`opcode` 标签	线路值	描述
`OpSeal`	`0x21`	使用服务器密封密钥加密 blob — 用于 TLS 会话票证
`OpUnseal`	`0x22`	解密先前由 `OpSeal` 加密的 blob。如果密封密钥已轮换，则返回 `ErrExpired`
`OpRPC`	`0x23`	执行在服务器上注册的命名函数。所有连接类型均可用
`OpCustom`	`0x24`	执行服务器配置中设置的自定义函数。仅对不受限制的连接可用
`OpPing`	`0xF1`	健康检查 — 服务器将载荷作为 `OpPong` 回显，不涉及 HSM 或密钥查找

`keyless_request_exec_duration_per_opcode`

类型： Histogram
标签： type, error

测量执行单个操作的时间，从处理开始到产生响应为止。对于由 PKCS#11 HSM 支持的操作，这包括从池中等待会话的完整时间以及 HSM 密码操作时间。

此指标不包括请求等待连接信号量槽位的时间。该时间由 keyless_request_total_duration_per_opcode 捕获。

`type` 标签

操作码被分组为更粗粒度的类别：

`type` 标签	包含的操作码
`rsa`	`OpRSADecrypt`、所有 `OpRSASign`、所有 `OpRSAPSSSign`
`ecdsa`	所有 `OpECDSASign*`
`ed25519`	`OpEd25519Sign`
`rpc`	`OpRPC`
`custom`	`OpCustom`
`other`	`OpSeal`、`OpUnseal`、`OpPing`、`OpPong`、`OpResponse`、`OpError`
`unknown`	任何无法识别的操作码字节

`error` 标签

对于成功的请求，值为 no error。所有其他值表示操作失败。

`error` 标签	描述	常见原因
`no error`	操作成功完成	—
`cryptography error`	HSM 或签名操作失败	PKCS#11 会话池耗尽（`resource pool timed out`）、HSM 返回错误、密钥类型不匹配
`key not found due to no matching SKI/SNI/ServerIP`	密钥查找未返回结果	密钥未加载到密钥库、请求中的 SKI 不正确
`read failure`	操作期间 I/O 读取错误	读取密钥文件时磁盘错误
`version mismatch`	不支持协议版本	客户端和服务器版本不一致
`bad opcode`	收到未知操作码	发送了 `OpCustom` 但未配置自定义处理程序
`unexpected opcode`	响应操作码被用作请求	客户端将 `OpPong`、`OpResponse` 或 `OpError` 作为请求发送
`malformed message`	TLV 解析失败	损坏或截断的数据包
`internal error`	非密码学服务器端故障	Sealer 为 nil、RPC 调度错误
`certificate not found`	证书查找失败	证书未加载
`sealing key expired`	`OpUnseal` blob 太旧无法解密	TLS 会话票证密钥轮换 — blob 使用已退役的密钥密封
`remote configuration error`	远程 key server 配置错误	密钥指向不可达或配置错误的远程 key server

`keyless_request_total_duration_per_opcode`

类型： Histogram
标签： type, error（与 keyless_request_exec_duration_per_opcode 相同的值）

测量满足请求的总时间，从请求数据包从线路读取到响应字节写回客户端为止。

total_duration = exec_duration + response_write_time

两个时间戳都在已持有连接信号量之后捕获，因此信号量队列等待时间不包括在任一直方图中。在正常负载下，总持续时间和执行持续时间大致相等。两者之间的差距增大表示写回客户端缓慢 — 例如 key server 与 Cloudflare 边缘之间的网络反压。

`keyless_key_load_duration`

类型： Histogram
标签： 无

测量密钥库为每个请求定位并返回私钥所需的时间，按 SKI、SNI 和服务器 IP 索引。

对于基于文件的密钥库，这是 map 查找，通常低于毫秒级。
对于 PKCS#11 或 HSM 密钥库，如果密钥引用未缓存在内存中，这可能包括到 HSM 的网络往返。

此指标针对所有签名和解密操作记录：OpRSADecrypt、所有 OpRSASign*、所有 OpRSAPSSSign*、所有 OpECDSASign* 和 OpEd25519Sign。

不为 OpPing、OpSeal、OpUnseal、OpRPC 或 OpCustom 记录，这些操作不需要私钥查找。

`keyless_failed_connection`

类型： Counter
标签： 无

统计连接级传输故障。此指标反映网络或 TLS 层的问题 — 不统计签名错误或密钥查找失败，这些在持续时间直方图的 error 标签中报告。

场景	是否计数？
TLS 握手失败	否
TLS 握手前客户端断开连接 (EOF)	否
TLS 后确定连接信任级别失败	是
已建立连接上的非 EOF 读取错误	是
传递响应时写入错误	是
读取超时 — 优雅连接排空	否
签名错误，包括 PKCS#11 池超时	否
未找到密钥	否

`certificate_expiration_timestamp_seconds`

类型： Gauge
标签： source, serial_no, cn, hostnames, ca, server, client

将 key server 加载的每张证书的过期时间（NotAfter）报告为 Unix 时间戳。每张证书发出一个时间序列。

此指标在以下情况下更新：

启动时，针对服务器身份验证证书（auth_cert）和 Cloudflare CA 证书（cloudflare_ca_cert）。
每次成功的入站 TLS 连接时，针对连接客户端呈现的对等证书。

标签	描述
`source`	启动证书的 file path；来自入站连接的 peer 证书为 `listener: <addr>`
`serial_no`	证书序列号
`cn`	主题 Common Name
`hostnames`	排序后的 DNS Subject Alternative Names 逗号分隔列表
`ca`	如果证书是 CA 证书则为 `1`，否则为 `0`
`server`	如果证书包含 `ExtKeyUsageServerAuth` 则为 `1`，否则为 `0`
`client`	如果证书包含 `ExtKeyUsageClientAuth` 则为 `1`，否则为 `0`

PromQL 查询示例

按密钥类型的签名吞吐量

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

按错误类型的错误率

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

RSA 签名的第 99 百分位延迟

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

接近 10 秒的值表示 PKCS#11 会话池耗尽。有关增加会话池大小的指导，请参阅扩展和基准测试和您的 HSM 文档。

第 99 百分位密钥加载延迟

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

此处出现峰值而执行持续时间没有相应峰值，表明密钥库查找本身较慢 — 可能是磁盘 I/O 问题或 PKCS#11 对象枚举延迟。

连接失败率

rate(keyless_failed_connection_total[5m])

持续非零速率表示 Cloudflare 网络与 key server 之间的网络或 TLS 问题。

30 天内证书过期告警

(certificate_expiration_timestamp_seconds - time()) / 86400 < 30