性能指标的口径选择

核心结论（BLUF）：性能指标的口径（Metric Methodology）是衡量、评估、优化与保障分布式系统及 AI 应用稳定性的基石。指标口径不一致是导致跨团队扯皮、容量评估失真、告警失效与 SLA 虚标的根源。构建生产级可观测体系，必须从物理测量锚点、时间聚合窗口、数学统计模型（分位数/直方图）与业务过滤边界四个维度，对吞吐量、时延、可用性及大模型专用指标进行严格的标准化定义。

前言：性能工程中的"巴别塔"困境

在互联网架构与企业数字化系统中，常常出现以下场景：

• 前端 vs 后端："用户反馈页面白屏卡顿了 5 秒，但后端 APM 监控显示接口平均耗时只有 30ms。"

• 测试 vs 运维："压测报告显示单机能扛 10 万 QPS，线上刚跑上 2 万 QPS 数据库连接池就打爆崩溃。"

• 算法 vs 平台："大模型推理服务声称吐字速度达到 50 Tokens/s，前端用户却依然觉得答案输出严重卡顿。"

这些现象的本质，并非某一方在数据上造假，而是不同角色所采用的"性能指标口径"存在根本性偏差。

┌─────────────────────────────────────────────────────────────────────────────┐
│                           不同视角下的性能指标口径差异                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
 [用户终端/前端] ──► 测量端到端体验耗时 (包含 DNS、TCP 握手、SSL、渲染、排队)
                                       │
 [API 网关接入层] ──► 测量反向代理耗时 (包含鉴权、限流、路由分发、Body 解析)
                                       │
 [微服务应用层] ──► 测量方法执行耗时 (包含 RPC 序列化、业务逻辑、连接池排队)
                                       │
 [底层数据库/缓存] ──► 测量引擎执行耗时 (仅计算纯 SQL 解析与数据扫描执行时间)

测量锚点的微小移动、统计聚合算法的选择错误、或者是成功与失败请求的过滤边界差异，都会让最终汇报出的性能数字相差数倍甚至数十倍。

本文将系统性拆解吞吐量、响应时间、可用性、并发度以及大模型时代的核心指标口径，剖析背后的数学原理与工程陷阱，并提供一套生产级指标度量规范与实现代码。

一、 吞吐量指标口径辨析：QPS、TPS、RPS、OPS 与 BPS

吞吐量（Throughput）是衡量系统在单位时间内处理工作量极限的核心维度。然而，"工作量"这一概念在不同的抽象层次有着完全不同的计算口径。

                               ┌───────────────────────────┐
                               │   客户端业务请求 (Transaction)│
                               └─────────────┬─────────────┘
                                             │ 1 个用户结账操作
                                             ▼
                               ┌───────────────────────────┐
                               │ 触发 3 次 HTTP API (Request)│
                               └─────────────┬─────────────┘
                                             │ 拆解为微服务调用
                                             ▼
                               ┌───────────────────────────┐
                               │ 衍生 8 个数据库查询 (Query) │
                               └───────────────────────────┘

1.1 QPS（Queries Per Second，每秒查询数）

• 标准定义：系统每秒钟处理的查询请求数量。

• 口径陷阱：

  • 数据库视角 ：单指数据库引擎每秒执行的 SELECT 语句数。

  • 搜索引擎/DNS 视角：指每秒处理的检索 Query 次数。

  • 应用服务视角：很多团队误将所有 HTTP 请求都称为 QPS，混淆了读请求与写请求的消耗差异。

  • 批处理陷阱 ：若客户端发送一个 Batch 请求（内含 100 条数据的批量查询），该记为 1 个 QPS 还是 100 个 QPS？生产标准规范：必须明确区分 Network-QPS（网络请求次数 = 1）与 Item-QPS（底层业务条目数 = 100）。

1.2 TPS（Transactions Per Second，每秒事务数）

• 标准定义 ：系统在单位时间内完成的完整业务事务的数量。

• 口径界定：

  • 一个 Transaction 必须具备完整的业务闭环（如："用户下单并支付成功"）。

  • 在分布式微服务架构中，1 个 TPS 往往对应着 1 个网关请求、5 个 RPC 调用、3 个数据库事务以及 2 个 MQ 消息投递。

  • 口径计算公式：

    TPS = 成功完成的业务事务总数 / 统计时长(秒)

  • 如果一个业务流程中途抛出异常回滚，在严格口径下不能计入有效业务 TPS ，但必须计入系统的负载压力 TPS。

1.3 RPS（Requests Per Second，每秒请求数）

• 标准定义：服务节点在网络层或应用层每秒接收并处理的 HTTP/RPC 请求报文数量。

• 与 QPS/TPS 的关系：

  • RPS 是纯粹面向协议层与通信层的技术度量。

  • 在单接口压力测试中：1 个只读请求 = 1 RPS = 1 QPS。

  • 在复杂业务中：1 TPS ≈ N 个 RPS。

1.4 OPS 与 BPS（操作数与带宽吞吐）

• OPS（Operations Per Second） ：主要用于存储系统（如 Redis、HBase、Kafka），衡量每秒读写操作指令的总数（如 Redis 的 GET、SET、HGETALL）。

• BPS（Bits/Bytes Per Second）：网络每秒传输的字节量。在富媒体或大数据场景下，即便 RPS 很低，BPS 也可能迅速打满网卡带宽，成为真正的瓶颈。

吞吐量指标口径对比矩阵

指标名称	适用层次	度量实体	典型应用场景	关键排除/界定项
QPS	存储层 / 只读接口	单次数据查询操作	数据库、ES、缓存读能力评估	批量（Batch）操作需拆解条目统计
TPS	业务应用层	端到端完整业务事务	电商下单、支付结算、核心业务容量	包含多阶段原子性操作，非单一接口
RPS	网关层 / 网络层	HTTP / gRPC 协议请求	API 网关限流、负载均衡器容量规划	包含静态资源、健康检查等技术请求
OPS	基础组件层	单条指令执行次数	Redis、Kafka、NoSQL 吞吐评估	需结合指令复杂度（O(1) vs O(N)）评估
BPS	基础设施/网络	物理网络吞吐字节数	CDN、对象存储、视频流媒体	需区分上行带宽（Inbound）与下行带宽（Outbound）

二、 响应耗时指标口径深水区：平均值陷阱与分位数模型

在所有性能指标中，响应耗时（Latency / Response Time / Duration） 是最具欺骗性、也最容易被错误统计的指标。

2.1 平均响应时间（Avg RT）的"数学骗局"

许多技术报告依然习惯使用"平均响应时间（Average Latency）"来汇报系统性能，但在现代分布式系统中，平均值几乎毫无工程价值，甚至具有严重误导性。

为什么平均值不可信？

1. 长尾分布（Long-Tail Distribution）：互联网服务的耗时不是正态分布，而是高度偏态的长尾分布或双峰分布（大部分请求在 10ms 内完成，少数慢请求需要 2000ms）。

2. 掩盖真实故障：假设系统处理了 100 个请求，99 个耗时 1ms，1 个耗时 1000ms

   平均耗时 = (99 * 1ms + 1 * 1000ms) / 100 = 10.99ms

   从平均耗时看，系统"非常健康"（仅约 11ms）；但对于那个遭遇 1000ms 的用户而言，体验是灾难性的。在微服务调用链（1 个用户请求触发 50 次下游调用）中，根据概率乘法法则，几乎 100% 的前端用户都会撞上长尾慢请求。

   请求数量 (Count)
   ▲
   │ ███ (绝大多数请求集中在低耗时区: 5~10ms)
   │ █████
   │ ███████
   │ █████████ ◄── [平均值被拉高至 35ms，无法反映真实众数]
   │ │ │
   │──┴────────┴─────────────────────────────████ (长尾慢请求: 500ms+)──► 耗时 (Latency)
   P50 P90 P99

2.2 分位数模型（Percentiles）：P50、P90、P95、P99、P99.9

现代可观测性标准强制要求采用分位数（Percentiles）作为核心耗时口径：

• P50（Median，中位数）：表示 50% 的请求耗时都低于该值，反映系统在通常情况下的基准性能。

• P90 / P95：用于日常 SLA 监控，代表大多数正常用户的体感上限。

• P99（99 分位数） ：表示 99% 的请求耗时低于该值，仅有 1% 的最慢请求高于该值。这是衡量系统高可用与尾部延迟（Tail Latency）的黄金标准。

• P99.9（三千分位数）：衡量金融级、核心交易链路等极度严苛场景下的极端抖动。

2.3 严禁对分位数进行"二次平均"：直方图（Histogram）的正确姿势

在分布式架构中，最常见的数学错误是："将 10 台服务器各自计算出的 P99 耗时相加求平均，作为集群的 P99 耗时。"

【致命数学错误】:
集群 P99 ≠ (NodeA_P99 + NodeB_P99 + NodeC_P99) / 3

分位数是一个位置次序统计量，不具备代数加和性。如果 Node A 承载了 10 万请求，Node B 承载了 100 个请求，两者的 P99 绝对不可直接平均。

正确工程方案：Prometheus 直方图（Histogram Buckets）

正确的做法是在各节点上收集原始耗时的分布桶（Buckets），将各桶的计数值在服务端进行累加，最后统一通过插值算法计算全局分位数。

Prometheus 标准计算公式：
histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))

耗时分桶区间 (Buckets):
Bucket 1: (0ms ~ 5ms]     ──► Count: 5000
Bucket 2: (5ms ~ 10ms]    ──► Count: 3500
Bucket 3: (10ms ~ 25ms]   ──► Count: 1200
Bucket 4: (25ms ~ 50ms]   ──► Count: 250
Bucket 5: (50ms ~ 100ms]  ──► Count: 45
Bucket 6: (100ms ~ +Inf]  ──► Count: 5

通过汇总所有节点的 Bucket 计数值，监控服务端能够精确还原全局请求的累积分布函数（CDF），计算出数学上严谨的全局 P99。

2.4 测量锚点全链路拆解：你在哪个点测耗时？

耗时指标必须严格标明测量锚点（Measurement Anchor）：

[用户浏览器] ──(1. 网络传输与DNS)──► [CDN/WAF] ──(2. 专线接入)──► [API 网关]
                                                                     │
                                                             (3. 内部 RPC)
                                                                     │
                                                                     ▼
[数据库 / 存储] ◄──(5. SQL 执行与等待)── [微服务实例] ◄──(4. 排队与反序列化)

1. 端到端耗时（Client E2E Latency）：从用户点击按钮、浏览器发起 DNS 解析，到接收完最后一个字节并完成 DOM 渲染的总耗时。

2. 网关耗时（Gateway Latency）：网关接收到首字节，到将响应首字节/尾字节发回客户端的耗时。

3. 服务处理耗时（Server Processing Time）：从进入 Controller 容器开始，到完成业务逻辑退出 Controller 的时间。

4. 内部 RPC/SQL 耗时（Downstream Dependency Latency）：客户端库发起调用到拿到响应的时间（包含连接池获取等待时间）。

口径规范原则 ：对外 SLA 承诺必须以网关或客户端接入层 口径为准；对内系统优化与排查必须细化至服务内纯计算耗时与下级依赖耗时。

三、 可用性与成功率指标口径：状态码、业务语义与时间维度

"系统可用性达到 99.99%"这句承诺，如果在口径上没有严格约定，往往是一纸空文。

                              ┌───────────────────────────┐
                              │      所有进入系统的请求   │
                              └─────────────┬─────────────┘
                                            │
                     ┌──────────────────────┴──────────────────────┐
                     ▼                                             ▼
          ┌─────────────────────┐                       ┌─────────────────────┐
          │   HTTP 2xx / 3xx    │                       │    HTTP 4xx / 5xx   │
          └──────────┬──────────┘                       └──────────┬──────────┘
                     │                                             │
          ┌──────────┴──────────┐                       ┌──────────┴──────────┐
          ▼                     ▼                       ▼                     ▼
     业务成功              业务失败 (code!=0)       客户端错误 (404/400)   服务端故障 (500/502)
   (True Success)        (Business Failure)      (Client Error)        (System Crash)

3.1 HTTP 协议状态码口径 vs 业务状态码口径

• 协议层成功率（Transport Success Rate）：

  • 计算公式：HTTP Status < 500 的请求数 / 总请求数。

  • 陷阱 ：在许多国内系统设计中，接口无论发生什么异常，HTTP 状态码一律返回 200 OK，真实的错误封装在 JSON 体内部（如 {"code": 50001, "msg": "Database error"}）。如果仅按 HTTP 状态码统计，成功率永远是 100%，掩盖全部线上故障。

• 业务语义成功率（Business Success Rate）：

  • 计算公式：HTTP 200 且 业务 Code == 0 的请求数 / 总请求数。

  • 陷阱 ：需将业务预期内失败 （如"密码输入错误"、"商品库存不足"、"用户余额不足"）与系统级异常（如"SQL 超时"、"空指针异常"）剥离开。库存不足属于正常的业务逻辑，不应拉低系统技术可用性。

3.2 4xx 客户端错误到底算谁的？

• 400（Bad Request）/ 401（Unauthorized）/ 404（Not Found）/ 422（Unprocessable Entity）：

  • 通常口径下不计入服务端系统可用性故障。

  • 特例情况：如果版本发布后，由于前后端字段定义不一致，导致前端大量触发 400 错误，必须计入版本交付质量（Release Quality）口径。

3.3 时间维度可用性（Uptime SLA）vs 请求维度成功率（Request-based SLR）

衡量系统可用性通常有两种口径，两者的计算结果可能大相径庭：

1. 基于时间的可用性（Time-based Availability）

可用性 = (统计总分钟数 - 故障停机分钟数) / 统计总分钟数 * 100%

• 缺陷：忽略了流量的潮汐效应。若系统在凌晨 4 点宕机 10 分钟（几乎无用户访问），与在上午 10 点大促高峰期宕机 10 分钟（数万订单丢失），在时间口径下扣减的可用性完全一致，这与实际业务损失严重脱节。

2. 基于请求的成功率（Request-based Availability / SLR

可用性 = 成功请求总数 / (成功请求总数 + 系统级失败请求总数) * 100%

• 优势：精确映射业务损失，高并发时段的故障会被赋予极高的权重，符合真正的生产运营诉求。

SLA"几个9"停机时间对照表

可用性等级	年允许停机时间	月允许停机时间	天允许停机时间	适用业务等级
99% (2个9)	3.65 天	7.20 小时	14.40 分钟	内部测试环境、非核心离线系统
99.9% (3个9)	8.76 小时	43.80 分钟	1.44 分钟	一般企业级业务、边缘微服务
99.99% (4个9)	52.56 分钟	4.38 分钟	8.64 秒	电商交易核心、用户认证中心
99.999% (5个9)	5.26 分钟	25.90 秒	0.86 秒	电信级、金融核心结算平台

四、 并发与资源容量指标口径：利特尔法则与资源饱和度

很多团队在讨论并发时，往往把"在线用户数"、"并发用户数"和"系统吞吐量"混为一谈。

4.1 用户视角并发 vs 系统在途请求（In-flight Requests）

• 在线用户数（Online Users）：当前在系统建立连接、或最近 15 分钟有心跳的用户总数（大部分处于阅读或思考的静止状态，不消耗 CPU）。

• 并发用户数（Concurrent Users / Virtual Users）：在同一瞬时周期内，正在向服务端发送请求的用户数量。

• 系统在途请求数（In-flight Requests）：服务端已经接收、但尚未完全处理完成并返回的请求总数。

4.2 利特尔法则（Little's Law）在并发口径中的数学推导

在稳定的排队系统中，在途请求数（Concurrency）、吞吐量（Throughput）与响应时间（Latency）之间存在严格的数学守恒关系：

Concurrency = Throughput * Latency
并发度 (在途请求数) = 吞吐量 (RPS) × 平均响应时间 (秒)

实战推导案例：

假设一个系统的接口响应耗时为 50ms（0.05 秒），要求系统支撑 10,000 RPS 的吞吐量：

系统并发线程/连接需求 = 10,000 * 0.05 = 500 Concurrency

如果下游数据库发生抖动，响应时间从 50ms 恶化至 500ms（增加 10 倍），为了维持 10,000 RPS 的吞吐量：

系统并发线程/连接需求 = 10,000 * 0.5 = 5,000 Concurrency

结论：时延变慢会导致系统内部的并发请求数迅速堆积，从而打爆 Tomcat 线程池或 Go 协程队列，引发全链路雪崩。

4.3 资源利用率（Utilization）与饱和度（Saturation）的 USE 模型

在度量底层资源性能时，必须遵循 Brendan Gregg 提出的 USE 原则（Utilization, Saturation, Errors）：

┌────────────────────────────────────────────────────────────────────────┐
│                        USE 资源性能分析三要素                          │
├──────────────────┬─────────────────────────────────────────────────────┤
│ 1. 利用率        │ 资源在单位时间内处于繁忙状态的百分比                │
│   (Utilization)  │ (如: CPU 利用率 75%, 内存占用 80%)                  │
├──────────────────┼─────────────────────────────────────────────────────┤
│ 2. 饱和度        │ 资源过载后在队列中排队等待的任务深度                │
│   (Saturation)   │ (如: CPU Load 超过 Core 数, 磁盘 IO 等待队列深度)   │
├──────────────────┼─────────────────────────────────────────────────────┤
│ 3. 错误数        │ 资源产生硬件或系统级错误的次数                      │
│   (Errors)       │ (如: 网卡丢包、磁盘坏道、内存 ECC 纠错)             │
└──────────────────┴─────────────────────────────────────────────────────┘

关键口径提示 ：高利用率不等于系统瓶颈，高饱和度才是性能崩溃的先兆 。例如 CPU 利用率达到 90%，但负载（Load）未超过物理核心数且没有任务排队，系统依然处于高效工作状态；反之，若 CPU 利用率仅 30%，但磁盘 I/O 饱和度打满导致线程全部处于 D 状态（Uninterruptible Sleep），系统已濒临瘫痪。

五、 大模型（LLM/GenAI）时代特有的全新性能口径

在生成式 AI 与大语言模型（LLM）架构下，传统的 QPS、RT 等指标已无法真实刻画系统的性能特征。大模型推理的自回归特性，催生了一批全新的度量衡口径。

                               【Prompt 输入】
                                     │
                          (Prefill 阶段: 计算密集型)
                                     ▼
                     ┌───────────────────────────────┐
                     │ 首字吐出 (TTFT)               │
                     └───────────────┬───────────────┘
                                     │
                          (Decode 阶段: 访存密集型)
                                     ▼
                     ┌───────────────────────────────┐
                     │ 逐字生成 (TPOT / Inter-Token) │ ──► (持续流式推送)
                     └───────────────┬───────────────┘
                                     │
                                     ▼
                     ┌───────────────────────────────┐
                     │ 全文完成 (E2E Latency)        │
                     └───────────────────────────────┘

5.1 TTFT（Time to First Token，首字延迟）

• 定义：从客户端发出 Prompt 请求，到接收到大模型返回的第一个 Token（字符片段）之间的时间间隔。

• 物理本质 ：对应 GPU 推理引擎的 Prefill（预填充）阶段。

• 口径影响因素：

  • 用户输入 Prompt 的长度（Prompt Tokens 越多，矩阵乘法计算量越大，TTFT 越长）。

  • 是否命中 Prompt Cache / Prefix Cache。若完全命中缓存，TTFT 可从数秒降低至几十毫秒。

5.2 TPOT（Time Per Output Token，每 Token 耗时 / 间字时延）

• 定义 ：在生成过程中，平均每输出一个 Token 所消耗的时间。

• 物理本质 ：对应 GPU 推理引擎的 Decode（解码）阶段。

• 换算关系：

  TPOT = (端到端总耗时 - 首字延迟 TTFT) / (输出的 Completion Tokens 总数 - 1)
  单流吐字速率 (Tokens/s) = 1000 / TPOT(ms)

• 体验口径界限：

  • 人类的平均阅读速度约为 10~20 字符/秒（约合 15~25 Tokens/s，即 TPOT 约 40~60ms）。

  • 若系统的 TPOT > 100ms（即吐字速度低于 10 Tokens/s），用户会产生明显的卡顿体感。

5.3 TPS（Tokens Per Second，系统吞吐量口径）

在大模型网关中，不能仅用 RPS 衡量容量，必须统计 Token 吞吐量：

1. Prompt Tokens/s：系统每秒处理的输入 Token 总量（代表计算吞吐能力）。

2. Completion Tokens/s：系统每秒生成的输出 Token 总量（代表显存带宽与访存吞吐能力）。

3. 加权总 TPS ：由于输入与输出在 GPU 计算中的算力消耗比例通常在 1:3 到 1:5 左右，简单地将 Prompt Tokens 与 Completion Tokens 相加会造成容量评估偏差。推荐统一按加权系数折算为标准化算力单位。

5.4 命中率口径（Cache Hit Rate）

在大模型 RAG 或长文本系统中，Cache 命中率对吞吐与成本有着决定性影响。必须细分三种口径：

• Exact Cache Hit Rate（精确文本完全命中率）：Prompt 完全一致，直接读取 Redis 缓存返回结果。

• Prefix / KV Cache Hit Rate（前缀缓存命中率）：Prompt 的前半部分（如系统 System Prompt + RAG 知识库上下文）命中了 vLLM 等引擎的显存 KV Cache。

• Semantic Cache Hit Rate（语义缓存命中率）：基于向量相似度召回的近似缓存命中。

六、 生产级实战：构建标准化指标度量与监控代码

为了避免"口径定义全凭口头传达"的问题，必须在代码与可观测性配置层面固化标准口径。

以下提供一套基于 Python（FastAPI + Prometheus Client） 的生产级性能指标采集与分位数统计完整实现。

6.1 生产级 Prometheus 指标采集模块实现

import time
from typing import Callable
from fastapi import FastAPI, Request, Response
from prometheus_client import (
    Counter,
    Histogram,
    Gauge,
    generate_latest,
    CONTENT_TYPE_LATEST
)

app = FastAPI(title="Performance Metric Standard Demo")

# ==================== 1. 标准化指标定义 (遵循口径规范) ====================

# A. 吞吐量与成功率指标 (Counter)
# 规范：必须包含 method, path, http_status, biz_code 四个关键维度
HTTP_REQUESTS_TOTAL = Counter(
    name="http_requests_total",
    documentation="Total count of HTTP requests processed, partitioned by status and business code.",
    labelnames=["method", "path", "http_status", "biz_status"]
)

# B. 响应耗时指标 (Histogram - 采用科学的分桶对数分布)
# 规范：针对 Web 接口设置 5ms 到 10s 的阶梯桶，支持精准计算 P50, P90, P99
HTTP_REQUEST_DURATION_SECONDS = Histogram(
    name="http_request_duration_seconds",
    documentation="HTTP request latency distributions in seconds.",
    labelnames=["method", "path"],
    buckets=(
        0.005, 0.010, 0.025, 0.050, 0.075, 0.100,
        0.250, 0.500, 0.750, 1.000, 2.500, 5.000, 10.000
    )
)

# C. 并发度指标 (Gauge)
# 规范：严格统计当前服务实例内部的在途请求数 (In-flight Requests)
IN_FLIGHT_REQUESTS = Gauge(
    name="http_in_flight_requests",
    documentation="Current number of concurrent in-flight requests being processed."
)

# ==================== 2. 全局中间件：标准化埋点与口径收敛 ====================

@app.middleware("http")
async def performance_metrics_middleware(request: Request, call_next: Callable) -> Response:
    # 忽略监控与探针自身的流量，防止污染生产指标口径
    if request.url.path in ["/metrics", "/health", "/favicon.ico"]:
        return await call_next(request)

    path = request.url.path
    method = request.method
    
    # 1. 记录在途并发开始 (+1)
    IN_FLIGHT_REQUESTS.inc()
    start_time = time.perf_counter()
    
    http_status = 500
    biz_status = "unknown_error"

    try:
        response = await call_next(request)
        http_status = response.status_code
        
        # 尝试从自定义响应头中提取业务语义状态 (避免仅依赖 HTTP 状态码)
        # 例如业务侧注入的 X-Biz-Status: success / user_not_found
        biz_status = response.headers.get("X-Biz-Status", "success" if http_status < 400 else "failed")
        return response
    except Exception as exc:
        http_status = 500
        biz_status = "unhandled_exception"
        raise exc
    finally:
        # 计算精准的耗时 (秒)
        duration = time.perf_counter() - start_time
        
        # 2. 释放在途并发 (-1)
        IN_FLIGHT_REQUESTS.dec()
        
        # 3. 记录请求总数与状态口径
        HTTP_REQUESTS_TOTAL.labels(
            method=method,
            path=path,
            http_status=str(http_status),
            biz_status=biz_status
        ).inc()
        
        # 4. 记录耗时直方图
        HTTP_REQUEST_DURATION_SECONDS.labels(
            method=method,
            path=path
        ).observe(duration)

# ==================== 3. 暴露 Prometheus 监控端点 ====================

@app.get("/metrics")
async def metrics():
    return Response(
        content=generate_latest(),
        media_type=CONTENT_TYPE_LATEST
    )

@app.get("/api/v1/orders/{order_id}")
async def get_order(order_id: str, response: Response):
    # 模拟业务执行耗时
    time.sleep(0.035)  # 35ms 耗时
    response.headers["X-Biz-Status"] = "success"
    return {"order_id": order_id, "amount": 199.9, "status": "PAID"}

6.2 标准化 PromQL 查询看板（消除口径偏差）

在 Grafana 看板配置中，必须使用数学上严谨的 PromQL 查询语句：

1. 集群全局真实 QPS（每秒吞吐量）

sum(rate(http_requests_total[1m]))

2. 系统级技术成功率（排除 4xx，仅将 5xx 视作系统故障）

(
  sum(rate(http_requests_total{http_status!~"5.."}[1m])) 
  / 
  sum(rate(http_requests_total[1m]))
) * 100

3. 全局业务成功率（严格要求 HTTP 200 且 业务状态为 success）

(
  sum(rate(http_requests_total{http_status="200", biz_status="success"}[1m])) 
  / 
  sum(rate(http_requests_total[1m]))
) * 100

4. 全局集群 P99 响应耗时（基于直方图插值，严禁二次平均）

histogram_quantile(
  0.99, 
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
)

七、 性能指标口径治理避坑清单与落地 SOP

为了在企业内部彻底消除"指标歧义"，技术团队在制定与使用性能指标时，必须严格执行以下 五项铁律：

┌─────────────────────────────────────────────────────────────────────────────┐
│                       性能指标口径标准化落地五项铁律                        │
├──────────────────┬──────────────────────────────────────────────────────────┤
│ 1. 标明测量锚点  │ 凡是汇报 RT/耗时，必须显式声明测量位置                   │
│                  │ (如：客户端 E2E、网关接入层、微服务方法级、数据库引擎)   │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ 2. 抛弃单一均值  │ 全面废除"平均响应时间"，一律采用 P50 / P95 / P99 分位数  │
│                  │ 组合与直方图（Histogram）呈现分布                        │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ 3. 业务双轨统计  │ 可用性必须实行"协议状态码"与"业务语义码"双轨制统计       │
│                  │ 严禁直接使用 HTTP 200 代表业务执行成功                   │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ 4. 严禁分位数相加│ 严禁对跨机器、跨节点的分位数进行二次代数平均             │
│                  │ 必须在底层汇总 Bucket 计数后重新进行全局分位数运算       │
├──────────────────┼──────────────────────────────────────────────────────────┤
│ 5. 声明负载背景  │ 任何性能数字脱离了并发/负载背景均无意义                  │
│                  │ 描述指标必须附带上下文 (如："在 5000 RPS 负载下，P99 为  │
│                  │ 45ms，CPU 处于 65%")                                     │
└──────────────────┴──────────────────────────────────────────────────────────┘

结语

性能指标不仅是监控大盘上的几条曲线，更是研发团队、测试团队、运维架构师与业务业务方之间统一沟通的契约。

从明确区分 QPS 与 TPS 的边界，到识破平均值的数学陷阱、拥抱 P99 直方图，再到大模型时代准确刻画 TTFT 与 TPOT，只有当全团队在指标口径上达成完全一致的认知与工程落地规范时，性能调优与容量规划才不会沦为"盲人摸象"，系统的稳定性保障才真正拥有了坚固的度量基础。