📚 课程目录第2章 Envoy Access Log 基础

2. Envoy Access Log 基础：Access Log 的格式、字段含义与常见配置

Envoy Access Log（访问日志）是网关可观测性的核心数据源之一。它记录了每一个经过 Envoy 的请求与响应的元数据，包括来源 IP、目标路由、响应状态码、处理耗时等关键信息。在变更门禁场景中，Access Log 是验证流量是否符合预期、检测异常回滚的重要依据。

2.1 Access Log 的格式体系

Envoy 支持三种日志格式定义方式，按灵活度从低到高排列：

格式类型	配置方式	适用场景
默认格式	不显式指定 `format`，使用 Envoy 内置格式	快速验证、开发环境
字符串格式	通过 `format` 字段定义模板字符串，使用 `%FIELD%` 占位符	日常运维、固定字段输出
JSON 格式	通过 `json_format` 字段定义 JSON 结构，字段名与值一一映射	日志采集、结构化分析、变更门禁审计

推荐实践：在变更门禁环境中，始终使用 JSON 格式。它便于日志系统（如 Elasticsearch、Loki）直接解析，也方便在 CI/CD 流水线中通过脚本提取关键字段进行断言。

2.2 核心字段含义与分类

Access Log 字段按信息维度可分为以下五类。下表列出了变更门禁场景中最常用的字段：

分类	字段名（字符串格式）	含义	变更门禁用途
请求标识	`%REQ(X-REQUEST-ID)%`	请求唯一 ID（由上游或 Envoy 生成）	关联全链路追踪，定位变更影响的具体请求
	`%REQ(:METHOD)%`	HTTP 方法（GET/POST/PUT/DELETE 等）	过滤写操作请求，评估变更风险
	`%REQ(X-ENVOY-ORIGINAL-PATH?)%`	原始请求路径	判断请求是否命中变更后的路由规则
上游信息	`%UPSTREAM_CLUSTER%`	上游集群名称	确认流量是否被正确路由到新版本集群
上游信息	`%UPSTREAM_HOST%`	上游主机地址（IP:Port）	细粒度验证灰度比例，确认新版本实例是否接收流量
响应状态	`%RESPONSE_CODE%`	HTTP 响应状态码	检测错误率是否飙升（5xx 比例）
响应状态	`%RESPONSE_FLAGS%`	响应标志（如 `UH`、`UF`、`DC`）	识别上游不健康、超时、熔断等异常
耗时指标	`%DURATION%`	总请求耗时（毫秒）	评估变更是否引入性能退化
耗时指标	`%UPSTREAM_RESPONSE_DURATION%`	上游处理耗时（毫秒）	区分网络延迟与上游应用延迟
连接信息	`%DOWNSTREAM_REMOTE_ADDRESS%`	客户端 IP 地址	按来源 IP 做流量切分验证

注意：%RESPONSE_FLAGS% 是变更门禁中最重要的诊断字段之一。例如 DC（Dns Connection Failure）表示上游 DNS 解析失败，UF（Upstream Failure）表示上游连接失败。这些标志在变更后出现时，通常意味着路由配置或上游健康检查存在问题。

2.3 常见配置示例

2.3.1 字符串格式配置

admin:
  access_log:
  - name: envoy.access_loggers.file
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
      path: /var/log/envoy/access.log
      format: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?)% %PROTOCOL%\" %RESPONSE_CODE% %RESPONSE_FLAGS% %DURATION%ms upstream=%UPSTREAM_HOST% cluster=%UPSTREAM_CLUSTER%

2.3.2 JSON 格式配置（推荐用于变更门禁）

admin:
  access_log:
  - name: envoy.access_loggers.file
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
      path: /var/log/envoy/access.json
      json_format:
        timestamp: "%START_TIME%"
        method: "%REQ(:METHOD)%"
        path: "%REQ(X-ENVOY-ORIGINAL-PATH?)%"
        protocol: "%PROTOCOL%"
        response_code: "%RESPONSE_CODE%"
        response_flags: "%RESPONSE_FLAGS%"
        duration_ms: "%DURATION%"
        upstream_cluster: "%UPSTREAM_CLUSTER%"
        upstream_host: "%UPSTREAM_HOST%"
        client_ip: "%DOWNSTREAM_REMOTE_ADDRESS%"
        request_id: "%REQ(X-REQUEST-ID)%"

  配置要点：
  path 指定日志文件路径，建议使用 .json 后缀以区分格式。
json_format 中的 key 可以自定义，value 必须使用 %FIELD% 占位符。
Envoy 支持在 json_format 中嵌套对象，例如 {"upstream": {"host": "%UPSTREAM_HOST%", "cluster": "%UPSTREAM_CLUSTER%"}}。

2.4 Access Log 处理流程

下图展示了 Envoy 从接收到请求到输出 Access Log 的完整链路：

2.5 变更门禁中的字段选择策略

在变更门禁场景中，并非所有字段都需要记录。建议按以下优先级选择字段：

必选字段：%RESPONSE_CODE%、%RESPONSE_FLAGS%、%UPSTREAM_CLUSTER%、%DURATION% —— 用于判断变更是否引入错误或性能退化。
推荐字段：%REQ(X-REQUEST-ID)%、%UPSTREAM_HOST%、%REQ(:METHOD)% —— 用于流量追踪和灰度验证。
按需字段：%DOWNSTREAM_REMOTE_ADDRESS%、%REQ(X-ENVOY-ORIGINAL-PATH?)% —— 用于来源分析和路由验证。

性能考量：每增加一个字段，日志行长度和序列化开销都会增加。在变更门禁的高频采样场景下，建议将字段数量控制在 10 个以内，避免对 Envoy 性能产生显著影响。

2.6 常见问题与避坑

问题	原因	解决方案
日志中 `%UPSTREAM_HOST%` 为空	请求在路由阶段失败，未到达上游	检查 `%RESPONSE_FLAGS%` 是否为 `NR`（No Route）或 `URX`（Upstream Retry Exceeded）
JSON 格式日志无法被解析	字段值中包含未转义的特殊字符	使用 `%REQ(X-HEADER):json%` 格式对 header 值进行 JSON 转义
日志文件轮转后丢失数据	未配置日志轮转策略	使用 `logrotate` 或 Envoy 内置的 `access_log_flush_interval` 和 `access_log_file_flush_interval_msec` 参数
变更后日志量暴增	采样率过高或日志级别不当	在变更门禁期间使用 `sampling_rate` 控制采样比例，例如设置为 10%