3. Envoy 指标体系：内置统计指标与 Admin 接口暴露
Envoy 内置了丰富的统计指标系统，覆盖 Cluster、Listener、HTTP、TCP 四大核心维度。这些指标是 SLO 预算复核的数据基础，通过 Admin 接口可以实时获取原始指标值。本章将系统梳理指标分类、命名规则以及 Admin 接口的暴露方式。
3.1 指标分类与命名规则
Envoy 的统计指标采用 层级命名 结构，以点号 . 分隔，格式为：<作用域>.<对象名称>.<指标名>。下表列出四大维度的典型指标前缀与含义：
| 维度 | 指标前缀示例 | 典型指标 | 说明 |
|---|---|---|---|
| Cluster | cluster.<name>. |
upstream_rq_total, upstream_rq_5xx, membership_total |
上游集群健康、请求成功率、端点数量 |
| Listener | listener.<address>. |
downstream_cx_total, downstream_cx_active, server_ssl_handshake |
监听器连接数、TLS 握手状态 |
| HTTP | http.<stat_prefix>. |
downstream_rq_total, downstream_rq_2xx, downstream_rq_time |
HTTP 连接管理器请求计数、延迟分布 |
| TCP | tcp.<stat_prefix>. |
downstream_cx_total, downstream_cx_rx_bytes_total, upstream_cx_connect_fail |
TCP 代理连接、字节数、连接失败 |
命名要点： 指标名称中的
<name> 或 <stat_prefix> 由 Envoy 配置中的 stat_prefix 或集群名称决定。在 SLO 复核时，务必确认指标前缀与配置一致，避免统计口径错位。
3.2 核心指标详解
3.2.1 Cluster 指标
Cluster 指标直接反映上游服务的健康与性能，是 SLO 错误预算消耗的核心依据。
- upstream_rq_total：上游总请求数（含重试）。
- upstream_rq_2xx / 3xx / 4xx / 5xx：按响应码分类的请求数。
- upstream_rq_time：上游请求延迟直方图（P50/P95/P99）。
- membership_total / membership_healthy：集群端点总数与健康数。
- upstream_cx_connect_fail：连接上游失败次数。
3.2.2 Listener 指标
Listener 指标反映网关入口的连接状态，用于评估客户端接入的稳定性。
- downstream_cx_total：已接受的客户端连接总数。
- downstream_cx_active：当前活跃连接数。
- downstream_cx_destroy：因各种原因关闭的连接数。
- server_ssl_handshake：TLS 握手成功/失败次数。
3.2.3 HTTP 连接管理器指标
HTTP 指标是 SLO 复核中最常用的维度，直接对应请求成功率与延迟。
- downstream_rq_total：下行总请求数。
- downstream_rq_2xx / 4xx / 5xx：按响应码分类的下行请求。
- downstream_rq_time：请求处理时间直方图（毫秒）。
- downstream_cx_rx_bytes_total / tx_bytes_total：接收/发送字节数。
3.2.4 TCP 代理指标
TCP 指标用于四层代理场景，监控原始连接与流量。
- downstream_cx_total：TCP 下游连接总数。
- downstream_cx_rx_bytes_total / tx_bytes_total：TCP 流量字节数。
- upstream_cx_connect_fail：TCP 上游连接失败次数。
- upstream_cx_close：上游连接关闭次数。
3.3 Admin 接口暴露指标
Envoy 通过 Admin 接口 的 /stats 端点暴露所有统计指标。Admin 接口默认监听 127.0.0.1:9901，可在启动参数或配置文件中修改。
3.3.1 启用 Admin 接口
在 Envoy 配置的 admin 字段中指定监听地址：
admin:
access_log_path: /tmp/admin_access.log
address:
socket_address:
address: 0.0.0.0
port_value: 99013.3.2 获取指标数据
使用 curl 或浏览器访问 /stats 端点：
# 获取所有指标（纯文本格式）
curl http://127.0.0.1:9901/stats
# 获取 Prometheus 格式指标
curl http://127.0.0.1:9901/stats/prometheus
# 获取 JSON 格式指标
curl http://127.0.0.1:9901/stats?format=json
格式选择建议： 在 SLO 预算复核场景中，推荐使用
/stats/prometheus 端点，其输出可直接被 Prometheus 抓取，便于后续计算错误预算消耗率。
3.4 指标暴露架构
下图展示了 Envoy 内部指标从采集到 Admin 接口暴露的完整链路：
3.5 指标过滤与定制
在生产环境中，Envoy 可能产生数千个指标。Admin 接口支持按正则表达式过滤，减少数据量：
# 仅查看 cluster 相关指标
curl http://127.0.0.1:9901/stats?filter=^cluster\\.此外，Envoy 允许通过 bootstrap 配置中的 stats_config 字段定制指标统计方式：
stats_config:
stats_tags:
- tag_name: "cluster_name"
regex: "^cluster\\.(.+?)\\."
use_all_default_tags: true
注意： 在 SLO 预算复核时，不要直接使用原始指标名称做聚合。建议先通过
stats_tags 提取标签（如集群名、监听器地址），再按标签分组计算错误率，避免因指标名称中的动态部分导致统计遗漏。
3.6 指标采集最佳实践
- 统一采集频率： 建议 Prometheus 每 15s 抓取一次
/stats/prometheus，与 SLO 复核窗口（如 1 分钟）对齐。 - 关注关键指标： 优先采集
upstream_rq_5xx、downstream_rq_5xx、upstream_rq_time等直接影响 SLO 的指标。 - 避免指标爆炸： 对于动态集群（如 K8s 端点），使用
stats_matcher排除不必要的直方图指标。 - 启用直方图百分位： 在配置中设置
histogram_buckets，确保延迟指标包含 P50/P95/P99 分位值。