Metrics 监控系统

quicX Metrics 为 QUIC/HTTP3 实现提供全面的可观测性：54+ 指标覆盖 UDP、QUIC、HTTP/3 各层，无锁设计，支持 Prometheus 格式导出。所有指标操作为 O(1) 复杂度——原子操作避免锁竞争、预分配槽位实现零堆分配，单次指标更新 < 10ns；核心指标自动埋点，可运行时启停。本文尝试回答以下问题：

1. 指标系统怎么做到零开销？ —— 见”系统架构”与”性能保证”；
2. 54+ 指标如何组织、各覆盖什么？ —— 见”指标分类”的 13 个功能类别；
3. 如何在项目中接入与导出？ —— 见”使用指南”。

1. 系统架构

核心组件

┌─────────────────────────────────────────────────┐
│           Application Code                      │
│  (UDP, QUIC, HTTP/3, Memory Pool, etc.)        │
└────────────────┬────────────────────────────────┘
                 │ Metrics::CounterInc()
                 │ Metrics::GaugeSet()
                 ▼
┌─────────────────────────────────────────────────┐
│         Metrics Registry (Lock-Free)            │
│  ┌──────────────┐  ┌──────────────┐            │
│  │   Counter    │  │    Gauge     │            │
│  │  (Atomic)    │  │  (Atomic)    │            │
│  └──────────────┘  └──────────────┘            │
└────────────────┬────────────────────────────────┘
                 │ ExportPrometheus()
                 ▼
┌─────────────────────────────────────────────────┐
│         Prometheus Exporter                     │
│  # TYPE metric_name counter                    │
│  metric_name{labels} value                     │
└─────────────────────────────────────────────────┘

实现原理

1. 无锁槽位分配

// 预分配槽位数组
std::vector<MetricSlot> slots_;  // 初始化时分配

// O(1) 注册
MetricID RegisterCounter(name, help) {
    size_t id = next_id_.fetch_add(1);  // 原子递增
    slots_[id] = MetricSlot{name, help, COUNTER};
    return id;
}

2. 原子操作更新

// Counter 递增 - 无锁
void CounterInc(MetricID id, uint64_t delta = 1) {
    slots_[id].value.fetch_add(delta, std::memory_order_relaxed);
}

// Gauge 设置 - 无锁
void GaugeSet(MetricID id, uint64_t value) {
    slots_[id].value.store(value, std::memory_order_relaxed);
}

3. 高效导出

std::string ExportPrometheus() {
    std::ostringstream oss;
    for (auto& slot : slots_) {
        if (slot.type == COUNTER) {
            oss << "# TYPE " << slot.name << " counter\n";
            oss << slot.name << " "
                << slot.value.load(std::memory_order_relaxed) << "\n";
        }
        // ... Gauge, Histogram
    }
    return oss.str();
}

2. 指标分类

1. UDP 层指标 (6个)

指标名称	类型	说明
udp_packets_rx	Counter	UDP 接收包总数
udp_packets_tx	Counter	UDP 发送包总数
udp_bytes_rx	Counter	UDP 接收字节总数
udp_bytes_tx	Counter	UDP 发送字节总数
udp_dropped_packets	Counter	UDP 丢包总数
udp_send_errors	Counter	UDP 发送错误总数

用途：监控网络层健康状况，识别网络拥塞和丢包问题。

2. QUIC 连接层指标 (5个)

指标名称	类型	说明
quic_connections_active	Gauge	当前活跃连接数
quic_connections_total	Counter	累计创建连接数
quic_connections_closed	Counter	累计关闭连接数
quic_handshake_success	Counter	握手成功次数
quic_handshake_fail	Counter	握手失败次数

用途：监控连接生命周期，评估握手成功率。

3. QUIC 包层指标 (6个)

指标名称	类型	说明
quic_packets_rx	Counter	QUIC 包接收总数
quic_packets_tx	Counter	QUIC 包发送总数
quic_packets_retransmit	Counter	重传包总数
quic_packets_lost	Counter	丢包总数
quic_packets_dropped	Counter	丢弃包总数
quic_packets_acked	Counter	确认包总数

用途：监控传输层可靠性，计算丢包率和重传率。

4. QUIC 流层指标 (7个)

指标名称	类型	说明
quic_streams_active	Gauge	当前活跃流数
quic_streams_created	Counter	累计创建流数
quic_streams_closed	Counter	累计关闭流数
quic_streams_bytes_rx	Counter	流接收字节总数
quic_streams_bytes_tx	Counter	流发送字节总数
quic_streams_reset_rx	Counter	接收 RESET 次数
quic_streams_reset_tx	Counter	发送 RESET 次数

用途：监控流管理和数据传输，识别流异常。

5. RTT 性能指标 (3个)

指标名称	类型	说明
rtt_smoothed_us	Gauge	平滑 RTT (微秒)
rtt_variance_us	Gauge	RTT 方差 (微秒)
rtt_min_us	Gauge	最小 RTT (微秒)

用途：监控网络延迟，评估连接质量。

6. 拥塞控制指标 (6个)

指标名称	类型	说明
congestion_window_bytes	Gauge	当前拥塞窗口 (字节)
congestion_events_total	Counter	拥塞事件总数
slow_start_exits	Counter	退出慢启动次数
bytes_in_flight	Gauge	在途字节数
pacing_rate_bytes_per_sec	Gauge	Pacing 速率 (字节/秒)
pacing_delay_us	Histogram	Pacing 延迟 (微秒)

用途：监控拥塞控制算法，优化吞吐量。

7. 错误统计指标 (4个)

指标名称	类型	说明
errors_protocol	Counter	协议错误次数
errors_internal	Counter	内部错误次数
errors_flow_control	Counter	流控制错误次数
errors_stream_limit	Counter	流限制错误次数

用途：监控系统健康状况，快速定位问题。

8. 流控制指标 (2个)

指标名称	类型	说明
quic_flow_control_blocked	Counter	连接级流控阻塞次数
quic_stream_data_blocked	Counter	流级流控阻塞次数

用途：监控流控制状态，优化窗口大小。

9. 超时指标 (2个)

指标名称	类型	说明
idle_timeout_total	Counter	空闲超时次数
pto_count_total	Counter	PTO 超时次数

用途：监控超时事件，调整超时参数。

10. HTTP/3 指标 (4个)

指标名称	类型	说明
http3_requests_total	Counter	HTTP/3 请求总数
http3_requests_active	Gauge	当前活跃请求数
http3_requests_failed	Counter	失败请求总数
http3_push_promises_rx	Counter	接收 Push Promise 次数

用途：监控 HTTP/3 业务指标，评估服务质量。

11. 内存池指标 (4个)

指标名称	类型	说明
mem_pool_allocated_blocks	Gauge	已分配块数
mem_pool_free_blocks	Gauge	空闲块数
mem_pool_allocations	Counter	分配次数
mem_pool_deallocations	Counter	释放次数

用途：监控内存使用，优化内存池配置。

12. Frame 统计指标 (2个)

指标名称	类型	说明
frames_rx_total	Counter	接收 Frame 总数
frames_tx_total	Counter	发送 Frame 总数

用途：监控协议层活动，分析通信模式。

13. ACK 相关指标 (3个)

指标名称	类型	说明
ack_delay_us	Histogram	ACK 延迟 (微秒)
ack_ranges_per_frame	Histogram	每个 ACK Frame 的 Range 数
ack_frequency	Gauge	ACK 频率 (每秒 ACK 数)

用途：监控 ACK 行为，优化确认策略。

3. 使用指南

初始化

#include <quicx/common/metrics.h>

// 1. 配置 Metrics
quicx::MetricsConfig config;
config.enable_ = true;             // 启用 metrics
config.initial_slots_ = 1024;      // 初始槽位数
config.prefix_ = "quicx_";         // 指标名称前缀

// 2. 初始化 Metrics 系统
quicx::Metrics::Initialize(config);

导出 Prometheus 格式

// 获取 Prometheus 格式的 metrics 数据
std::string metrics_data = quicx::Metrics::ExportPrometheus();

// 输出到文件
std::ofstream file("/var/lib/prometheus/quicx.prom");
file << metrics_data;
file.close();

// 或通过 HTTP endpoint 提供
// (参见 HTTP/3 Metrics Endpoint 部分)

HTTP/3 Metrics Endpoint

#include <quicx/http3/if_server.h>

// 创建 HTTP/3 server
auto server = quicx::IServer::Create(settings);

// 配置 server
quicx::Http3ServerConfig config;
config.quic_config_.cert_file_ = "server.crt";
config.quic_config_.key_file_ = "server.key";

// 启用 metrics endpoint
config.metrics_.http_enable_ = true;
config.metrics_.http_path_ = "/metrics";

// 初始化并启动
server->Init(config);
server->Start("0.0.0.0", 8443);

访问 metrics：

# 使用 HTTP/3 客户端
curl --http3 https://localhost:8443/metrics

4. 性能保证

基准测试结果

Benchmark                          Time        CPU
-------------------------------------------------
CounterInc/1                    8.2 ns     8.2 ns
CounterInc/100                  820 ns     820 ns
GaugeSet/1                      7.5 ns     7.5 ns
GaugeSet/100                    750 ns     750 ns
ExportPrometheus/100          45.2 µs    45.2 µs
ExportPrometheus/1000        452.0 µs   452.0 µs

性能特性

1. 极低延迟：单次更新 < 10ns
2. 线性扩展：性能与指标数量线性相关
3. 零竞争：无锁设计，多线程无竞争
4. 内存高效：预分配，无运行时分配

内存占用

每个指标槽位：~128 字节
1000 个指标：~128 KB
导出缓冲区：~100 KB (临时)

5. 最佳实践

1. 合理配置槽位数

// 根据预期指标数量配置
config.initial_slots_ = expected_metrics * 1.5;  // 留 50% 余量

2. 定期导出

// 每 15 秒导出一次（Prometheus 默认抓取间隔）
std::thread exporter([]{
    while (running) {
        std::string data = Metrics::ExportPrometheus();
        WriteToFile("/var/lib/prometheus/quicx.prom", data);
        std::this_thread::sleep_for(std::chrono::seconds(15));
    }
});

3. 监控关键指标

优先监控：

• 连接数 (quic_connections_active)
• 丢包率 (quic_packets_lost / quic_packets_tx)
• RTT (rtt_smoothed_us)
• 错误率 (errors_*)
• 吞吐量 (quic_streams_bytes_*)

4. 设置告警

# Prometheus 告警规则示例
groups:
  - name: quicx_alerts
    rules:
      - alert: HighPacketLoss
        expr: rate(quic_packets_lost[5m]) / rate(quic_packets_tx[5m]) > 0.05
        annotations:
          summary: "High packet loss rate (> 5%)"

      - alert: HighRTT
        expr: rtt_smoothed_us > 100000  # > 100ms
        annotations:
          summary: "High RTT detected"

      - alert: TooManyErrors
        expr: sum(rate(errors_protocol[5m])) > 10
        annotations:
          summary: "High error rate"

6. 故障排查

问题：指标未更新

原因：Metrics 未初始化或已禁用

解决：

// 确保初始化
Metrics::Initialize(config);

// 确保启用
config.enable_ = true;

问题：导出数据为空

原因：没有注册任何指标

解决：

// 确保调用了 InitializeStandardMetrics()
// 这在 Metrics::Initialize() 中自动调用

问题：性能下降

原因：槽位数不足，导致重新分配

解决：

// 增加初始槽位数
config.initial_slots_ = 2048;  // 或更大

7. 扩展开发

添加自定义指标

// 1. 在 metrics_std.h 中声明
struct MetricsStd {
    static MetricID MyCustomMetric;
};

// 2. 在 metrics_std.cpp 中定义
MetricID MetricsStd::MyCustomMetric = kInvalidMetricID;

// 3. 在 InitializeStandardMetrics() 中注册
MetricsStd::MyCustomMetric =
    Metrics::RegisterCounter("my_custom_metric", "My custom metric");

// 4. 在代码中使用
Metrics::CounterInc(MetricsStd::MyCustomMetric);

添加 Histogram 支持

// 注册 Histogram
MetricID latency_hist = Metrics::RegisterHistogram(
    "request_latency_us",
    "Request latency in microseconds",
    {10, 50, 100, 500, 1000, 5000}  // buckets
);

// 记录观测值
Metrics::HistogramObserve(latency_hist, latency_value);

8. 关联 RFC

• Prometheus 文档
• QUIC RFC 9000
• HTTP/3 RFC 9114