4、Envoy 访问日志格式配置：默认格式、JSON 格式、自定义格式、日志字段详解

Envoy 访问日志是服务网格可观测性的核心数据源，记录了每个请求的完整生命周期。掌握日志格式配置，是进行流量拓扑分析和故障排查的基础。Envoy 支持三种日志格式：默认格式（字符串）、JSON 格式（结构化）和自定义格式（混合模式）。

4.1 默认格式（Default Format）

Envoy 默认使用 ENVOY_DEFAULT_FORMAT 字符串格式，包含 14 个核心字段，以空格分隔。该格式适合快速查看，但解析效率低，不推荐用于生产。

[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"\n

示例输出：

[2025-04-10T08:12:34.567Z] "GET /api/v1/products HTTP/1.1" 200 - 0 1234 567 89 "10.0.0.1" "curl/7.68.0" "abc-123-def" "product-service.default.svc.cluster.local" "10.0.0.2:8080"

4.2 JSON 格式（JSON Format）

JSON 格式将日志输出为结构化的 JSON 对象，每个字段有明确的键名。这是服务网格可观测性的标准格式。

{
  "start_time": "2025-04-10T08:12:34.567Z",
  "method": "GET",
  "path": "/api/v1/products",
  "protocol": "HTTP/1.1",
  "response_code": 200,
  "response_flags": "-",
  "bytes_received": 0,
  "bytes_sent": 1234,
  "duration": 567,
  "upstream_service_time": 89,
  "x_forwarded_for": "10.0.0.1",
  "user_agent": "curl/7.68.0",
  "request_id": "abc-123-def",
  "authority": "product-service.default.svc.cluster.local",
  "upstream_host": "10.0.0.2:8080"
}

配置示例（Envoy YAML）：

access_log:
- name: envoy.access_loggers.file
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
    path: /dev/stdout
    log_format:
      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%"
        bytes_received: "%BYTES_RECEIVED%"
        bytes_sent: "%BYTES_SENT%"
        duration: "%DURATION%"
        upstream_service_time: "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%"
        x_forwarded_for: "%REQ(X-FORWARDED-FOR)%"
        user_agent: "%REQ(USER-AGENT)%"
        request_id: "%REQ(X-REQUEST-ID)%"
        authority: "%REQ(:AUTHORITY)%"
        upstream_host: "%UPSTREAM_HOST%"

4.3 自定义格式（Custom Format）

自定义格式允许混合使用字符串和字段占位符，适用于需要特定分隔符或前缀的场景。Envoy 使用 format 字段定义。

access_log:
- name: envoy.access_loggers.file
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
    path: /dev/stdout
    log_format:
      format: "[%START_TIME%] %REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% -> %RESPONSE_CODE% (%DURATION%ms)\n"

示例输出：

[2025-04-10T08:12:34.567Z] GET /api/v1/products -> 200 (567ms)

4.4 日志字段详解

Envoy 访问日志字段可分为 6 大类：时间、请求、响应、连接、上游、动态元数据。下表列出故障排查中最关键的 20 个字段：

4.5 日志格式选择决策流程

以下流程图帮助你在不同场景下选择合适的日志格式：

4.6 日志字段与流量拓扑的映射关系

在服务网格流量拓扑分析中，Envoy 日志字段直接映射到拓扑图的各个元素：

4.7 实战：快速切换日志格式

在 Istio 环境中，可以通过 istioctl 或 kubectl 动态修改 Envoy 日志格式，无需重启 Pod：

# 查看当前 Envoy 日志配置
istioctl proxy-config log <pod-name>.<namespace>

# 动态切换为 JSON 格式（临时生效，Pod 重启后恢复）
istioctl proxy-config log <pod-name>.<namespace> --level default:info --format json

# 持久化修改（通过 EnvoyFilter 或 Sidecar 配置）
kubectl apply -f - <<EOF
apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: access-log-json
  namespace: istio-system
spec:
  configPatches:
  - applyTo: NETWORK_FILTER
    match:
      context: ANY
      listener:
        filterChain:
          filter:
            name: "envoy.filters.network.http_connection_manager"
    patch:
      operation: MERGE
      value:
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
          access_log:
          - name: envoy.access_loggers.file
            typed_config:
              "@type": "type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog"
              path: /dev/stdout
              log_format:
                json_format:
                  start_time: "%START_TIME%"
                  method: "%REQ(:METHOD)%"
                  path: "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%"
                  response_code: "%RESPONSE_CODE%"
                  response_flags: "%RESPONSE_FLAGS%"
                  duration: "%DURATION%"
                  upstream_host: "%UPSTREAM_HOST%"
EOF