📚 课程目录第4章延迟指标定义

4. 延迟指标采集：从网关日志到分布式追踪的指标管道搭建

在策略即代码的延迟诊断体系中，指标采集是排障的“第一公里”。入口路由的延迟数据必须经过一条结构化的管道，从原始的网关日志逐级加工为可被策略引擎消费的分布式追踪指标。本章将拆解这条管道的每一层，并给出可落地的搭建方案。

4.1 指标管道的三层架构

延迟指标管道并非单一工具，而是一个分层数据流。每一层解决不同的问题：原始日志的采集、结构化指标的提取、以及跨服务调用链的关联。

层级	数据形态	典型工具	延迟信息粒度
L1：日志采集层	原始访问日志（文本/JSON）	Filebeat / Fluentd / Vector	单次请求的响应时间（RT）
L2：指标聚合层	时间序列指标（Counter/Histogram）	Prometheus / VictoriaMetrics	P50/P95/P99 延迟、错误率
L3：分布式追踪层	Span 链路数据	Jaeger / OpenTelemetry Collector	上下游各阶段耗时、瓶颈定位

策略视角： 策略引擎通常消费 L2 的聚合指标进行阈值告警，但在排障时需下钻到 L1 和 L3 获取原始证据。管道设计必须支持从聚合指标到原始日志/追踪的“一键下钻”能力。

4.2 L1：网关日志采集与结构化

入口路由（如 Kong / APISIX / Envoy）的访问日志是延迟数据的源头。采集阶段的核心任务是将非结构化文本转换为可解析的键值对。

4.2.1 日志格式标准化

以 Kong 为例，推荐使用自定义日志格式，确保包含关键延迟字段：

# Kong 自定义日志格式（nginx 变量）
log_format policy_trace '$remote_addr - $remote_user [$time_local] '
                        '"$request_method $request_uri $server_protocol" '
                        '$status $body_bytes_sent '
                        '$request_time $upstream_response_time '
                        '$upstream_connect_time $upstream_header_time '
                        '"$http_x_request_id" "$http_x_b3_traceid"';

  关键字段说明：
  $request_time：网关处理总耗时（含上游响应）
$upstream_response_time：上游服务响应时间
$upstream_connect_time：与上游建立连接的时间
$http_x_request_id / $http_x_b3_traceid：用于关联追踪的请求标识

4.2.2 采集器配置要点

使用 Filebeat 采集日志时，需配置多行合并与字段解析：

# filebeat.yml 关键配置
filebeat.inputs:
- type: log
  paths:
    - /var/log/kong/access.log
  parsers:
    - ndjson: ~  # 如果日志为 JSON 格式
  multiline:
    pattern: '^\d+\.\d+\.\d+\.\d+'  # 以 IP 开头为新请求
    negate: true
    match: after

output.elasticsearch:
  hosts: ["http://elasticsearch:9200"]
  index: "gateway-logs-%{+yyyy.MM.dd}"

4.3 L2：从日志到时间序列指标的聚合

原始日志无法直接用于策略引擎的实时判断，需要聚合为时间序列指标。这一层通常由 Prometheus 配合日志导出器（exporter）或直接由网关的 Prometheus 插件完成。

4.3.1 指标定义与标签设计

延迟指标必须包含足够的标签维度，以支持策略引擎按路由、状态码、上游服务进行切片分析。

# Prometheus 指标示例（由 Kong Prometheus 插件暴露）
# HELP kong_http_request_duration_ms HTTP 请求延迟（毫秒）
# TYPE kong_http_request_duration_ms histogram
kong_http_request_duration_ms_bucket{service="user-service",route="get_user",status="200",le="10"} 120
kong_http_request_duration_ms_bucket{service="user-service",route="get_user",status="200",le="50"} 450
kong_http_request_duration_ms_bucket{service="user-service",route="get_user",status="200",le="200"} 520
kong_http_request_duration_ms_bucket{service="user-service",route="get_user",status="200",le="+Inf"} 530
kong_http_request_duration_ms_sum{service="user-service",route="get_user",status="200"} 28450
kong_http_request_duration_ms_count{service="user-service",route="get_user",status="200"} 530

标签爆炸警告： 避免将 x_request_id 等高基数标签加入 Prometheus 指标。高基数标签会导致存储膨胀和查询性能下降。应将高基数信息保留在日志层，通过 trace_id 关联。

4.3.2 聚合管道搭建步骤

暴露指标端点： 在网关启用 Prometheus 插件（如 Kong 的 prometheus 插件），或使用 nginx-lua-prometheus 库。
配置抓取： 在 Prometheus 中添加网关目标，设置合理的抓取间隔（通常 15s）。
定义记录规则： 预计算常用的延迟分位数，减少策略查询时的计算开销。

# prometheus 记录规则示例
groups:
  - name: gateway_latency_records
    rules:
      - record: route:p99_latency_ms:5m
        expr: |
          histogram_quantile(0.99,
            sum(rate(kong_http_request_duration_ms_bucket[5m])) by (service, route, le)
          )
      - record: route:error_rate:5m
        expr: |
          sum(rate(kong_http_request_duration_ms_count{status=~"5.."}[5m])) by (service, route)
          /
          sum(rate(kong_http_request_duration_ms_count[5m])) by (service, route)

4.4 L3：分布式追踪——从指标到调用链

当聚合指标显示某路由延迟异常时，需要分布式追踪来定位具体是网关、上游服务还是数据库导致的延迟。这一层通过 OpenTelemetry 实现端到端的上下文传播。

4.4.1 追踪上下文注入

网关在转发请求时，必须注入追踪头（traceparent / x-b3-traceid），并记录网关自身的 Span。

# OpenTelemetry 在 Kong 中的配置（通过 opentelemetry 插件）
plugins:
  - name: opentelemetry
    config:
      endpoint: http://otel-collector:4318/v1/traces
      resource_attributes:
        service.name: kong-gateway
      headers:
        - "Authorization: Bearer ${OTEL_AUTH_}"
      propagation:
        - tracecontext
        - baggage

4.4.2 指标与追踪的关联策略

策略引擎在检测到延迟违规时，需要自动生成指向对应追踪的链接。这要求指标标签中包含 trace_id 的采样信息。

关联方式	实现方法	适用场景
日志-追踪关联	在日志中输出 trace_id，通过日志系统跳转到 Jaeger	人工排障
指标-追踪关联	在 Prometheus 指标中增加 `sample_trace_id` 标签（仅对慢请求采样）	自动策略触发时获取证据
自适应采样	基于延迟阈值动态决定是否记录完整追踪	降低存储成本，保留关键证据

4.5 管道整体架构图

下图展示了从网关日志到分布式追踪的完整指标管道，以及各层之间的数据流与关联关系。

4.6 管道验证与排障案例

搭建完成后，必须验证管道各层的数据一致性与延迟精度。以下是一个典型的验证流程：

注入测试请求： 使用 curl 发送带有已知延迟的请求（如通过 sleep 参数模拟上游延迟）。
检查 L1 日志： 确认 Elasticsearch 中日志的 request_time 字段值与实际延迟一致。
检查 L2 指标： 在 Prometheus 中查询对应路由的 kong_http_request_duration_ms_bucket，确认计数增加。
检查 L3 追踪： 在 Jaeger 中按 trace_id 搜索，确认 Span 时间线与日志记录匹配。
策略触发验证： 构造一个超阈值请求，确认策略引擎能正确读取指标并生成告警。

  常见排障点：
  日志与指标延迟不一致： 检查网关时钟同步（NTP），以及 Prometheus 抓取时间戳是否使用网关本地时间。
追踪丢失： 确认 OpenTelemetry 插件的采样率配置，以及 Collector 的负载是否过高导致丢数据。
策略引擎查询超时： 为 Prometheus 查询设置合理的超时时间（如 10s），并对高频查询使用记录规则预聚合。

4.7 小结

延迟指标管道是策略即代码诊断体系的数据基座。通过 L1 日志采集、L2 指标聚合、L3 分布式追踪的三层架构，既能满足策略引擎的实时检测需求，又能为排障提供完整的证据链。下一层的关键在于：如何将这些指标转化为策略引擎可执行的规则——这正是第 5 章的主题。