📚 课程目录第4章延迟信号（Latency）定义

4. 延迟信号（Latency）定义与日志字段映射

延迟（Latency）是衡量系统处理请求所花费时间的核心指标。在 Golden Signals 体系中，延迟直接反映用户体验和系统性能瓶颈。本节将深入探讨延迟在日志中的具体体现形式，并设计标准化的字段映射方案。

4.1 延迟的三种典型体现

在日志工程实践中，延迟通常以三种形式出现，分别对应不同的观测视角：

体现形式	定义	典型场景	观测目标
请求耗时	从客户端发起请求到收到完整响应的时间	HTTP API 调用、RPC 调用	端到端用户体验
响应时间	服务端从接收请求到开始发送响应的时间	数据库查询、中间件处理	服务端处理效率
处理时长	业务逻辑实际执行的时间（不含网络开销）	计算密集型任务、批处理作业	业务逻辑性能

实践要点： 在日志采集时，应同时记录这三种延迟的起始和结束时间戳，以便后续进行端到端链路追踪和分段分析。单一字段往往无法完整描述延迟的全貌。

4.2 关键字段设计

为了实现延迟指标的统一采集和分析，我们设计了三个核心字段。这些字段构成了延迟信号的基础数据模型。

字段名	数据类型	单位	说明	示例值
`duration_ms`	整数 (int64)	毫秒	请求从开始到结束的总耗时，包含所有子步骤	1523
`response_time`	浮点数 (float64)	毫秒	服务端处理请求并返回响应的净时间	1200.45
`elapsed`	整数 (int64)	毫秒	业务逻辑实际执行耗时，用于性能剖析	980

字段设计避坑： 避免使用 time、cost 等模糊字段名。必须明确单位（毫秒），并区分总耗时与净耗时。字段类型建议统一为毫秒级整数或浮点数，避免跨系统转换误差。

4.3 延迟字段映射关系

下图展示了延迟字段在典型请求链路中的映射关系，帮助理解各字段的采集位置和计算逻辑。

4.4 日志采集示例

以下是一个标准化的延迟日志采集示例，展示了三个核心字段在实际日志中的呈现方式：

{
  "timestamp": "2025-03-21T14:30:00.123Z",
  "service": "order-service",
  "endpoint": "/api/v1/orders",
  "method": "POST",
  "duration_ms": 1523,
  "response_time": 1200.45,
  "elapsed": 980,
  "status_code": 200,
  "trace_id": "abc123def456"
}

  字段计算规则：
  duration_ms = 响应完成时间戳 - 请求开始时间戳
response_time = 服务端处理完成时间戳 - 服务端接收请求时间戳
elapsed = 业务逻辑结束时间戳 - 业务逻辑开始时间戳

4.5 延迟指标聚合与告警

基于上述字段，我们可以构建以下关键延迟指标：

指标名称	计算方式	告警阈值建议	业务含义
P50 延迟	对 `duration_ms` 取中位数	< 500ms	半数用户感知的延迟水平
P99 延迟	对 `duration_ms` 取 99 分位	< 2000ms	最慢 1% 用户的体验
平均响应时间	对 `response_time` 取平均值	< 800ms	服务端整体处理效率
业务处理耗时	对 `elapsed` 取 P95	< 1500ms	业务逻辑性能瓶颈

最佳实践： 建议将 duration_ms 作为首要监控指标，response_time 用于服务端性能评估，elapsed 用于代码级性能优化。三者结合可快速定位延迟根因。