4. Envoy 访问日志（Access Log）配置：日志格式定义、JSON日志输出、日志采样与性能影响

访问日志是服务网格可观测性的基础数据源之一。Envoy 的访问日志记录了每个请求/响应的元数据，包括来源、目标、响应码、延迟、头部信息等。在生产环境中，合理的日志格式、输出方式与采样策略直接影响问题定位效率与代理性能。

4.1 访问日志格式定义

Envoy 通过 access_log 字段配置日志输出，支持两种格式定义方式：

• 默认格式（string）：使用 Envoy 内置的 %REQ(...)%、%RESP(...)%、%DYNAMIC_METADATA(...)% 等命令占位符拼接文本行。
• 结构化格式（json_format）：输出 JSON 对象，便于日志采集系统（如 Elasticsearch、Loki）直接解析。

# 文本格式示例（Envoy 配置片段）
access_log:
- name: envoy.access_loggers.file
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
    path: /dev/stdout
    format: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\" %RESPONSE_CODE% %RESPONSE_FLAGS% %DURATION%ms %UPSTREAM_HOST%

4.2 JSON 日志输出

JSON 格式是生产环境的首选。Envoy 支持在 typed_config 中直接定义 json_format 字段，输出结构化的日志对象。

# JSON 格式示例
access_log:
- name: envoy.access_loggers.file
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
    path: /dev/stdout
    json_format:
      start_time: "%START_TIME%"
      method: "%REQ(:METHOD)%"
      path: "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%"
      protocol: "%PROTOCOL%"
      response_code: "%RESPONSE_CODE%"
      response_flags: "%RESPONSE_FLAGS%"
      duration_ms: "%DURATION%"
      upstream_host: "%UPSTREAM_HOST%"
      bytes_received: "%BYTES_RECEIVED%"
      user_agent: "%REQ(USER-AGENT)%"
      x_request_id: "%REQ(X-REQUEST-ID)%"

JSON 日志输出到 stdout 后，通常由 sidecar 容器中的日志采集器（如 Fluent Bit、Filebeat）转发到集中存储。Envoy 也支持直接输出到 gRPC Access Log Service（ALS），适合大规模网格场景。

4.3 日志采样与性能影响

全量日志输出在高 QPS 场景下会带来显著的 CPU 和 I/O 开销。Envoy 通过 filter 机制实现采样控制，避免日志成为性能瓶颈。

采样策略对比

# 固定采样率配置：只记录 10% 的请求
access_log:
- name: envoy.access_loggers.file
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
    path: /dev/stdout
    json_format:
      duration_ms: "%DURATION%"
      response_code: "%RESPONSE_CODE%"
  filter:
    runtime_filter:
      runtime_key: "access_log.sample_rate"
      percent_sampled:
        numerator: 10
        denominator: HUNDRED

# 条件采样：只记录 5xx 错误请求
access_log:
- name: envoy.access_loggers.file
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
    path: /dev/stdout
    json_format:
      duration_ms: "%DURATION%"
      response_code: "%RESPONSE_CODE%"
      response_flags: "%RESPONSE_FLAGS%"
  filter:
    status_code_filter:
      comparison:
        op: GE
        value:
          default_value: 500
          runtime_key: "access_log.error_threshold"

4.4 访问日志处理流程

下图展示了 Envoy 从接收请求到输出访问日志的完整链路，以及采样过滤器在其中的位置。

4.5 生产配置建议

• 默认采样率：全量流量建议 1%~10%，错误流量（5xx、超时）可提升至 100%。
• 日志输出路径：优先使用 /dev/stdout，由容器运行时日志驱动采集，避免磁盘 I/O 竞争。
• JSON 字段精简：只保留诊断必需的字段，避免输出完整的请求/响应体。
• 动态采样：通过 runtime_key 绑定控制面配置，实现不停机调整采样率。
• 监控告警：对日志输出速率、丢弃日志数设置告警，防止日志积压导致 OOM。