Envoy Listener 统计指标全解从连接、TLS 到 QUIC 与 Listener Manager 的观测体系【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本文系统梳理 Envoy 中 Listener 层的全部统计指标体系涵盖通用连接指标、TLS 握手与证书指标、TCP/UDP/QUIC 传输指标、按工作线程per-handler拆分的连接指标以及 Listener Manager 生命周期指标并给出指标树命名规则、源码实现位置与集成测试验证方式帮助你在生产环境中完整构建针对接入层的可观测性与容量排障能力。统计指标树的整体结构Envoy 的 Listener 指标遵循统一的作用域scope命名规则每个 listener 拥有一棵以listener.address.*为根的指标树。如果该 listener 配置了stat_prefix字段即envoy.config.listener.v3.Listener.stat_prefix定义见 listener.proto则指标树根改为listener.stat_prefix.*。这一设计使得多环境共享同一监听地址时可以通过stat_prefix将不同业务流量的指标区分开。各子树的前缀规则如下指标类别指标树前缀通用连接指标listener.address.*TLS 握手与证书验证listener.address.ssl.*TLS/CA 证书有效期listener.address.ssl.certificate.cert_name.TCP 传输段统计listener.address.tcp_stats.*UDP 数据报统计listener.address.udp.*QUIC 连接统计listener.address.quic_stats.*按 handler线程拆分listener.address.handler.*Listener Manager 生命周期listener_manager.*Listener 通用连接指标每个 listener 都具备以下通用指标根前缀为listener.address.*名称类型说明downstream_cx_totalCounter总连接数downstream_cx_destroyCounter已销毁连接总数downstream_cx_activeGauge当前活跃连接数downstream_cx_length_msHistogram连接时长毫秒downstream_cx_transport_socket_connect_timeoutCounter在传输 socket 连接协商阶段超时的连接总数downstream_cx_overflowCounter因达到 listener 连接数上限而被拒绝的连接总数downstream_cx_overload_rejectCounter因配置的过载动作overload actions被拒绝的连接总数downstream_global_cx_overflowCounter因达到全局连接数上限被拒绝的连接总数connections_accepted_per_socket_eventHistogram每次 listener socket 事件接受的连接数downstream_pre_cx_timeoutCounter在 listener filter 处理阶段超时的 socket 数downstream_pre_cx_activeGauge当前正在进行 listener filter 处理的 socket 数extension_config_missingCounter因缺失 listener filter 扩展配置而关闭的连接总数network_extension_config_missingCounter因缺失网络 filter 扩展配置而关闭的连接总数no_filter_chain_matchCounter未匹配到任何 filter chain 的连接总数downstream_listener_filter_remote_closeCounterlistener filter 窥视peek数据时被远端关闭的连接总数downstream_listener_filter_errorCounterlistener filter 窥视数据时发生读取错误的总次数这些指标覆盖了连接生命周期的完整漏斗acceptdownstream_cx_total→ listener filter 处理downstream_pre_cx_*→ filter chain 匹配no_filter_chain_match→ 连接协商downstream_cx_transport_socket_connect_timeout→ 销毁downstream_cx_destroy。当出现连接被拒时可通过downstream_cx_overflow单 listener 限流、downstream_global_cx_overflow全局限流与downstream_cx_overload_reject过载管理动作三个指标快速定位是哪种保护机制生效。源码实现ALL_LISTENER_STATS 宏上述指标在源码中由 source/server/listener_stats.h 中的ALL_LISTENER_STATS宏统一定义通过 X-Macro 模式同时展开为ListenerStats结构体成员。各指标在 source/server/active_listener_base.h 的ActiveListenerImplBase构造时创建并挂到 listener 的 scope 上ActiveListenerImplBase(Network::ConnectionHandler parent, Network::ListenerConfig* config) : stats_({ALL_LISTENER_STATS(POOL_COUNTER(config-listenerScope()), POOL_GAUGE(config-listenerScope()), POOL_HISTOGRAM(config-listenerScope()))}), per_worker_stats_({ALL_PER_HANDLER_LISTENER_STATS( POOL_COUNTER_PREFIX(config-listenerScope(), parent.statPrefix()), POOL_GAUGE_PREFIX(config-listenerScope(), parent.statPrefix()))}), config_(config) {}两个细节值得注意downstream_cx_active与downstream_pre_cx_active的 Gauge 均声明为Accumulate模式——即多 worker 线程各自的局部值会被累加最终呈现为跨线程的总活跃数per-worker 指标通过parent.statPrefix()添加前缀这正是下节handler前缀的来源。扩展配置缺失指标的触发路径extension_config_missing与network_extension_config_missing两个计数器用于在基于扩展发现EDS/NEDS/LDS 扩展下发场景中检测配置尚未就绪的连接损失。从源码看二者均在 source/common/listener_manager/listener_impl.cc 的扩展配置查找失败路径上inc()并在 listener_impl.h 中以MissingListenerConfigStats结构统一声明。集成测试 test/integration/listener_extension_discovery_integration_test.cc 验证了当扩展配置缺失时连接被拒、计数器从 0 递增配置补齐后再次收数计数继续累加test/integration/network_extension_discovery_integration_test.cc 对网络扩展缺失做了同类断言。TLS 统计指标当 listener 的 filter chain 启用 TLSdownstream TLS context后会出现根前缀为listener.address.ssl.*的 TLS 指标名称类型说明connection_errorCounterTLS 连接错误总数不含证书验证失败handshakeCounterTLS 握手成功总数session_reusedCounterTLS 会话复用resumption成功总数no_certificateCounter未携带客户端证书即完成握手的连接总数fail_verify_no_certCounter因缺少客户端证书导致验证失败总数fail_verify_errorCounterCA 验证失败的连接总数fail_verify_sanCounterSAN 验证失败的连接总数fail_verify_cert_hashCounter证书固定pinning验证失败的连接总数ocsp_staple_failedCounter因 OCSP 策略合规失败而终止的连接总数ocsp_staple_omittedCounter未附带 OCSP 响应但连接成功总数ocsp_staple_responsesCounter有可用有效 OCSP 响应的连接总数无论客户端是否请求ocsp_staple_requestsCounter客户端请求 OCSP staple 的连接总数ciphers.cipherCounter使用指定密码套件完成握手的连接总数curves.curveCounter使用指定 ECDHE 曲线完成握手的连接总数sigalgs.sigalgCounter使用指定签名算法完成握手的连接总数versions.versionCounter使用指定 TLS 协议版本完成握手的连接总数其中ciphers.*、curves.*、sigalgs.*、versions.*是动态键指标dynamically named stats键值由实际握手结果决定因此监控时需要用通配符聚合。session_reused / handshake的比值可以直接反映 TLS 会话复用率是衡量握手开销优化的核心比例指标。TLS 与 CA 证书统计对每一张已加载的证书还会在listener.address.ssl.certificate.cert_name.下暴露证书级别指标见 cert_stats.rst名称类型说明expiration_unix_time_secondsGauge证书到期时间距 UNIX 纪元的秒数这是一个 Gauge 而非 Counter它的值就是证书过期的 Unix 时间戳因此可以直接与当前时间比较来驱动证书到期告警例如now 7d expiration_unix_time_seconds时触发换证流程无需解析文件系统。TCP 传输段统计当 listener 使用 TCP stats transport socket 时会在listener.address.tcp_stats.*下暴露操作系统提供的 TCP 传输层指标见 tcp_stats.rst名称类型说明cx_tx_segmentsCounter发送的 TCP 段总数cx_rx_segmentsCounter接收的 TCP 段总数cx_tx_data_segmentsCounter携带非零数据负载发送的 TCP 段总数cx_rx_data_segmentsCounter携带非零数据负载接收的 TCP 段总数cx_tx_retransmitted_segmentsCounter重传的 TCP 段总数cx_rx_bytes_receivedCounter已接收并已被 TCP 确认的载荷字节数cx_tx_bytes_sentCounter已发送的载荷字节数含重传字节cx_tx_unsent_bytesGaugeEnvoy 已交给操作系统但尚未发出的字节数cx_tx_unacked_segmentsGauge已发出但尚未被确认的段数cx_tx_percent_retransmitted_segmentsHistogram单个连接上被重传的段占比cx_rtt_usHistogram平滑后的往返时延估计微秒cx_rtt_variance_usHistogram往返时延的方差估计微秒值越高抖动越大官方文档特别注明这些指标由操作系统提供由于各操作系统及同一系统的不同版本可用指标与采样方式存在差异数值可能跨平台不一致。因此它们适合用于趋势对比同机、同版本与重传/RTT 恶化告警不适合跨环境横向绝对值比较。典型排障组合是cx_rtt_us突增 cx_tx_percent_retransmitted_segments升高 cx_tx_unacked_segments堆积通常指向下游网络链路劣化。UDP 统计指标UDP listener 在listener.address.udp.*下提供数据报级别指标名称类型说明downstream_rx_datagram_droppedCounter因内核缓冲区溢出或报文截断而丢弃的数据报数量该指标是 QUIC/UDP 接入侧丢包的直接信号由于 UDP 不保证交付downstream_rx_datagram_dropped持续增长说明内核接收队列过载例如 socket buffer 过小或应用侧读取不及时应结合内核netstat -su的RcvbufErrors/InErrors交叉验证。QUIC 统计指标当使用 QUIC stats debug visitor 时QUIC 连接指标会暴露在listener.address.quic_stats.*下名称类型说明cx_tx_packets_totalCounter发送报文总数cx_tx_packets_retransmitted_totalCounter重传报文总数cx_tx_amplification_throttling_totalCounter服务端握手响应阶段被拥塞放大限制amplification limiting节流抑制的报文数。该值偏高通常意味着 TLS 证书链过长一次往返无法完整发送cx_rx_packets_totalCounter接收报文总数cx_path_degrading_totalCounter检测到网络路径退化path degrading的次数cx_forward_progress_after_path_degrading_totalCounter路径退化后仍取得前向进展的次数cx_rtt_usHistogram平滑后的往返时延估计微秒cx_tx_estimated_bandwidthHistogram连接带宽估计值字节/秒cx_tx_percent_retransmitted_packetsHistogram连接上被重传的报文占比cx_tx_mtuHistogram该连接实际使用的最大报文大小cx_rx_mtuHistogram从对端接收到的最大报文大小两个值得关注的诊断指标cx_tx_amplification_throttling_total是 QUIC 服务端放大保护机制生效的次数若持续非零最常见的原因是证书链含 OCSP staple过大优化方向是精简证书链cx_path_degrading_total与cx_forward_progress_after_path_degrading_total的比值则刻画了连接在路径劣化后自愈的比例。Per-handler按线程Listener 统计除聚合指标外每个 listener 还在listener.address.handler.*下暴露按 handler 拆分的指标handler取值与 Envoy 线程模型对应主线程为main_thread各工作线程为worker_0、worker_1等工作线程数量由--concurrency启动参数控制。这组指标由 source/server/listener_stats.h 中的ALL_PER_HANDLER_LISTENER_STATS宏定义名称类型说明downstream_cx_totalCounter该 handler 上的总连接数downstream_cx_activeGauge该 handler 上的当前活跃连接数其主要用途是发现 per-handler / per-worker 的连接不均衡如果worker_3.downstream_cx_active显著高于其他 worker说明连接在内核 accept 队列到各 worker 的分配上出现了倾斜例如某个 worker 处理了更多 socket event可用于排查线程级热点。前缀的生成逻辑见 source/server/active_listener_base.hper-worker 指标以parent.statPrefix()即 handler 名为前缀挂在 listener scope 下。Listener Manager 统计指标Listener Manager 负责 listener 的动态增删与向 worker 分发其指标根前缀为listener_manager.*且指标名中的:会被替换为_。完整清单如下名称类型说明listener_addedCounter新增 listener 总数静态配置或 LDSlistener_modifiedCounter通过 LDS 修改的 listener 总数listener_removedCounter通过 LDS 移除的 listener 总数listener_stoppedCounter停止的 listener 总数listener_create_successCounter成功加入 worker 的 listener 对象总数listener_create_failureCounter加入 worker 失败的 listener 对象总数listener_in_place_updatedCounter走 filter chain 就地更新in-place update路径创建的 listener 对象总数total_filter_chains_drainingGauge当前正在 draining 的 filter chain 数total_listeners_warmingGauge当前处于 warming 状态的 listener 数total_listeners_activeGauge当前活跃的 listener 数total_listeners_drainingGauge当前处于 draining 状态的 listener 数workers_pinnedGauge启用 worker CPU 亲和性时被绑定 CPU 的 worker 线程数否则为 0workers_startedGauge布尔值1/0表示 listener 是否已在 worker 上完成初始化这组指标是验证 LDS 动态下发是否落地的核心观测面listener_added/listener_modified增长而listener_create_failure同时增长说明配置下发了但 listener 对象在 worker 上创建失败应检查端口冲突与 filter 初始化错误total_listeners_warming长时间不回落通常意味着 warming 阶段如订阅资源未就绪卡住listener_in_place_updated增长表示 Envoy 走的是 filter chain 就地热更新路径而非整 listener 重建可据此评估配置变更对存量连接的影响范围workers_started保持为 0 说明 worker 尚未完成 listener 初始化Envoy 还不接受流量可用于部署就绪探针判断。实践要点小结指标定位路径排障时按listener_manager.*配置是否下发→listener.address.*连接漏斗→ssl.*/quic_stats.*/tcp_stats.*传输层细节的层级下钻每一层都有独立的作用域前缀便于在监控系统中做聚合与下钻。Gauge 的 Accumulate 语义downstream_cx_active、downstream_pre_cx_active等 Gauge 采用Accumulate模式聚合多 worker 局部值见 source/server/listener_stats.h因此它们是总量而非每 worker 均值容量告警可直接基于该值设定。证书到期告警直接对ssl.certificate.cert_name.expiration_unix_time_seconds与当前时间比较即可实现证书到期监控不依赖额外解析。UDP/QUIC 丢包定位downstream_rx_datagram_dropped内核溢出/截断与 QUIC 的cx_tx_percent_retransmitted_packets、cx_rtt_us组合使用可以区分是接收侧资源不足还是链路质量问题。平台差异注意TCP stats 由操作系统提供跨 OS 数值可能不一致告警阈值应基于同平台基线设置。以上全部指标的文档定义集中在 docs/root/configuration/listeners/stats.rstTLS/证书/TCP 明细表分别位于 ssl_stats.rst、cert_stats.rst 与 tcp_stats.rst指标实现见 source/server/listener_stats.h 与 source/server/active_listener_base.hListener Manager 侧实现见 source/common/listener_manager/listener_manager_impl.cc。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考