Gloo网关请求转换调试日志功能详解

前言

在现代API网关的使用中，请求和响应的转换(transformations)是一个强大但复杂的特性。当转换规则变得复杂时，调试问题可能会变得困难。Gloo网关提供了一个实用的调试日志功能，可以帮助开发者理解转换过程中发生了什么。

调试日志功能概述

Gloo的调试日志功能允许开发者在转换过程中记录请求和响应的详细信息，包括：

• 转换前的请求头(headers)
• 转换前的请求体(body)
• 转换后的请求头
• 转换后的请求体

这个功能特别适用于以下场景：

1. 调试复杂的转换规则链
2. 验证转换是否按预期工作
3. 理解转换过程中数据的流动

重要安全提示

生产环境警告：调试日志会记录完整的请求和响应信息，可能包含敏感数据。请勿在生产环境中启用此功能。

配置调试日志的三种方式

Gloo提供了三种不同粒度的调试日志配置方式：

1. 单个转换阶段级别：针对特定的转换阶段启用日志
2. 虚拟服务级别：为虚拟服务中的所有转换阶段启用日志
3. 全局级别：为集群中的所有转换启用日志

实践示例

基础环境准备

首先，我们需要一个简单的虚拟服务(VirtualService)配置，将所有流量路由到一个测试上游(Upstream)：

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: test-debug-logs
  namespace: gloo-system
spec:
  virtualHost:
    domains:
    - '*'
    routes:
    - matchers:
       - prefix: /
      routeAction:
        single:
          upstream:
            name: postman-echo
            namespace: gloo-system

添加转换规则

接下来，我们添加两个阶段的请求头转换：

options:
  stagedTransformations:
    early:
      requestTransforms:
      - requestTransformation:
          transformationTemplate:
            headers:
              x-early-request-header: 
                text: "early"
    regular:
      requestTransforms:
      - requestTransformation:
          transformationTemplate:
            headers:
              x-regular-request-header: 
                text: "regular"

这个配置会在两个不同阶段添加不同的请求头：

• early阶段：添加x-early-request-header
• regular阶段：添加x-regular-request-header

启用调试日志

要为特定转换阶段启用调试日志，添加logRequestResponseInfo: true参数：

regular:
  requestTransforms:
  - requestTransformation:
      logRequestResponseInfo: true
      transformationTemplate:
        headers:
          x-regular-request-header: 
            text: "regular"

查看调试日志

1. 首先设置gateway-proxy的日志级别为debug：

kubectl port-forward -n gloo-system deployment/gateway-proxy 19000:19000
curl "localhost:19000/logging?level=debug" -X POST

2. 发送测试请求生成日志：

curl $(glooctl proxy url)/get

3. 查看gateway-proxy的日志输出：

kubectl logs -n gloo-system deployment/gateway-proxy

日志会显示转换前后的请求头和请求体，帮助你理解转换过程。

调试日志的典型输出

调试日志会显示如下信息：

[debug][filter] headers before transformation: 
':authority', 'localhost:8080'
':path', '/get'
':method', 'GET'
':scheme', 'http'
'user-agent', 'curl/7.87.0'
'accept', '*/*'

[debug][filter] body before transformation: 

[debug][filter] headers after transformation: 
':authority', 'localhost:8080'
':path', '/get'
':method', 'GET'
':scheme', 'http'
'user-agent', 'curl/7.87.0'
'accept', '*/*'
'x-early-request-header', 'early'
'x-regular-request-header', 'regular'

最佳实践建议

1. 按需启用：只在需要调试时启用日志功能，调试完成后立即关闭
2. 最小化范围：尽量在最小范围内启用日志（如特定转换阶段）
3. 日志级别管理：调试完成后记得将日志级别调回正常级别
4. 敏感数据处理：确保调试日志不会记录敏感信息

总结

Gloo的转换调试日志功能是一个强大的故障排除工具，可以帮助开发者深入理解请求转换过程。通过合理使用这个功能，可以显著提高复杂转换规则的开发和调试效率。记住在生产环境中要禁用此功能，以避免潜在的安全风险。