如何在AWS API Gateway访问日志中正确配置显示完整HTTP请求

问题根源 #

直接将VTL模板粘贴到日志格式框后，API Gateway会把它当作纯文本输出，因为没有启用自定义日志格式模式，也没有正确利用API Gateway日志系统支持的Velocity模板语言（VTL）解析能力。

正确配置步骤 #

1. 切换到自定义日志格式
   在API Gateway的Stages > 对应阶段 > Logs/tracing页面，找到"Log format"选项，选择Custom（不要用默认的CLF或预设JSON格式）。

2. 使用可解析的VTL模板作为日志格式
   将以下模板粘贴到自定义日志格式输入框，它会渲染出包含请求方法、头、参数、请求体的完整结构化日志：

   {
     "requestId": "$context.requestId",
     "httpMethod": "$context.request.httpMethod",
     "resourcePath": "$context.resourcePath",
     "requestHeaders": {
       #foreach($header in $input.params().header.keySet())
       "$header": "$util.escapeJavaScript($input.params().header.get($header))"#if($foreach.hasNext),#end
       #end
     },
     "queryParameters": {
       #foreach($param in $input.params().querystring.keySet())
       "$param": "$util.escapeJavaScript($input.params().querystring.get($param))"#if($foreach.hasNext),#end
       #end
     },
     "pathParameters": {
       #foreach($param in $input.params().path.keySet())
       "$param": "$util.escapeJavaScript($input.params().path.get($param))"#if($foreach.hasNext),#end
       #end
     },
     "requestBody": "$util.escapeJavaScript($input.body)",
     "sourceIp": "$context.identity.sourceIp",
     "userAgent": "$context.identity.userAgent"
   }
   

3. 重新部署API
   保存日志格式配置后，点击阶段页面的Deploy按钮，将更新后的配置部署到对应阶段。

关键说明 #

• VTL指令（#foreach、#if）会在日志生成时被API Gateway自动解析，替换为实际的请求数据。
• $util.escapeJavaScript用于转义请求中的特殊字符（如引号、换行），避免破坏日志的JSON结构。
• 如果需要查看原始未解析的JSON请求体，可将$input.body替换为$input.path('$')。
• 若请求为二进制类型，需先在API Gateway中配置支持对应的二进制媒体类型，否则请求体可能无法正确记录。

验证 #

发送测试请求后，前往CloudWatch对应的日志组查看日志，即可看到包含完整请求信息的结构化JSON日志。

内容的提问来源于stack exchange，提问作者Jack M