3. API延迟诊断基础：延迟的度量标准、分布式追踪原理与OpenTelemetry基础概念
在构建策略即代码（Policy-as-Code）的API延迟诊断体系之前，必须首先建立对延迟度量、追踪原理和观测数据采集的共识。本章将围绕这三个核心基础展开，为后续引入Sigstore观测标签提供度量与数据层面的支撑。
3.1 延迟的度量标准：p50 / p95 / p99
延迟（Latency）是衡量API响应速度的核心指标。仅依赖平均值（Average）容易掩盖长尾问题，因此业界普遍采用百分位延迟来描述分布特征。
| 百分位 | 含义 | 典型用途 |
|---|---|---|
| p50（中位数） | 50%的请求延迟低于该值 | 反映大多数用户的典型体验 |
| p95 | 95%的请求延迟低于该值 | 识别尾部延迟，SLO常用基准 |
| p99 | 99%的请求延迟低于该值 | 捕捉极端慢请求，诊断性能瓶颈 |
关键认知：在API延迟诊断场景中，p99的波动往往比p50更能暴露代码缺陷、资源争抢或下游依赖故障。策略即代码的规则引擎应优先对p99超阈值事件触发审计与标签绑定。
下图展示了同一API在不同百分位下的延迟分布对比，帮助直观理解长尾效应：
3.2 分布式追踪原理
在微服务架构中，一次API请求可能跨越多个服务、数据库和消息队列。分布式追踪通过Trace（追踪）和Span（跨度）模型，将请求的完整路径串联起来。
3.2.1 核心概念
- Trace：代表一次完整的请求或事务，由一组具有相同Trace ID的Span组成。
- Span：代表Trace中的一个工作单元，包含操作名称、开始/结束时间戳、属性（Attributes）和事件（Events）。
- Span Context：跨进程传递的追踪上下文，包含Trace ID、Span ID和采样标志。
3.2.2 追踪数据如何帮助诊断延迟
| 诊断场景 | 追踪数据提供的线索 |
|---|---|
| 单个服务变慢 | 该服务对应Span的持续时间异常增加 |
| 下游依赖超时 | Span中显示HTTP调用返回5xx或超时错误 |
| 串行调用过多 | Trace图中Span呈线性排列，无并行分支 |
| 资源竞争 | Span内出现锁等待事件或队列积压 |
策略即代码映射：分布式追踪中的Span Attributes是注入Sigstore标签的理想载体。例如，将
http.target、http.status_code、span.duration等属性直接映射为策略评估的输入变量。
下图展示了一个典型的分布式追踪结构，从入口网关到三个下游服务：
3.3 OpenTelemetry 基础概念
OpenTelemetry（OTel）是CNCF孵化的可观测性标准，提供统一的API、SDK和协议来生成、采集和导出遥测数据（Traces、Metrics、Logs）。
3.3.1 三大信号（Signals）
| 信号类型 | 作用 | 延迟诊断中的用途 |
|---|---|---|
| Traces | 记录请求在分布式系统中的完整路径 | 定位慢Span、分析调用链 |
| Metrics | 聚合后的数值指标（如请求数、延迟直方图） | 计算p50/p95/p99，触发告警 |
| Logs | 带时间戳的结构化事件记录 | 关联错误详情与Trace上下文 |
3.3.2 关键组件与数据流
- API：定义如何创建Span、添加属性、记录事件。
- SDK：实现API逻辑，包含采样、处理、导出等能力。
- Exporter：将遥测数据发送到后端（如Jaeger、Prometheus、Sigstore Receiver）。
- Context Propagation：通过W3C Trace Context标准，跨服务传递Trace ID。
注意：在策略即代码场景中，OpenTelemetry的Attributes（键值对）是策略评估的原始数据来源。务必确保关键属性（如
http.method、http.route、deployment.environment）在SDK初始化时被正确注入，否则策略引擎将无法获取有效的输入。
下图展示了OpenTelemetry SDK在微服务中的典型数据采集与导出流程：
3.4 三者如何协同支撑策略即代码
延迟度量标准（p50/p95/p99）提供目标，分布式追踪提供路径，OpenTelemetry提供数据管道。三者结合，使得策略引擎能够：
- 从Metrics中识别p99超阈值的API端点。
- 通过Trace定位导致延迟的Span及其所属服务。
- 利用OpenTelemetry Attributes提取上下文（如版本号、集群名、用户ID），生成Sigstore标签。
- 执行策略（如“如果p99 > 500ms且服务版本为v2，则绑定标签
latency:high”）。
实践建议：在OpenTelemetry SDK初始化时，通过Resource属性注入
service.name、service.version、deployment.environment。这些属性将自动附加到每个Span和Metric上，成为策略评估的稳定上下文，也是Sigstore标签体系的基础字段。