使用 CloudFront Functions 将自定义数据写入 CloudFront 访问日志

摘要：CloudFront Functions 新增 cf.logCustomData() 辅助方法，可将函数产生的自定义数据写入同一次请求的 CloudFront 访问日志。本文通过一个流量来源记录示例说明其配置和验证方法。

01 一、引言

04 四、总结

一、引言

CloudFront Functions 新增 cf.logCustomData() 辅助方法，可以把函数产生的业务决策或提取后的字段写入当前请求的 CloudFront 访问日志，与 URI、状态码和缓存结果保存在同一条记录中。过去，这些信息需要通过 console.log() 写入 CloudWatch Logs，再与 CloudFront 访问日志关联；现在可以减少跨日志查询，也不必为了记录一个业务字段而保留完整 Cookie 或查询字符串。

在 JavaScript 运行时 2.0 中，查看器请求函数写入 viewer-request-log-data，查看器响应函数写入 viewer-response-log-data。标准日志记录（v2）和实时日志均支持这两个字段，实际投递位置取决于日志配置。

下图显示自定义数据进入 CloudFront 访问日志的路径：

[图1]

二、示例：记录查询字符串中的流量来源

假设营销团队需要按 utm_source 分析流量，同时又不希望在自定义字段中重复保存完整查询字符串。以下示例使用查看器请求函数提取所需值，并通过标准日志记录（v2）投递。

2.1 编写并关联函数

创建一个使用 JavaScript 运行时 2.0 的 CloudFront Function：

import cf from 'cloudfront';

function handler(event) {
    var request = event.request;
    var query = request.querystring;

    if (query.utm_source || query.gclid) {
        cf.logCustomData(JSON.stringify({
            src: query.utm_source ? query.utm_source.value : '',
            gclid: query.gclid ? query.gclid.value : ''
        }));
    }

    return request;
}

发布函数，并将其关联到目标缓存行为的查看器请求（Viewer Request）事件。

假设查看器请求以下 URL：

https://www.example.com/page?utm_content=buffercf3b2&utm_medium=social&utm_source=www.amazon.com&utm_campaign=buffer

标准访问日志的 cs-uri-query 仍包含完整查询字符串；函数写入的 viewer-request-log-data 经 URL 解码后只包含选取的字段：

{"src":"www.amazon.com","gclid":""}

这样即可直接使用流量来源分析请求结果，无需从完整查询字符串中再次解析字段。

2.2 启用自定义日志字段

在 CloudFront 标准日志记录（v2）的 Field selection 中加入 viewer-request-log-data，并选择 CloudWatch Logs、Amazon Data Firehose 或 Amazon S3 作为目的地。如果没有选择该字段，即使函数调用了 cf.logCustomData()，投递结果中也不会包含其值。

实时日志也支持相同字段，但需另外配置 Kinesis Data Streams、采样率，并将实时日志配置关联到目标缓存行为。采样率低于 100% 时，并非每个请求都会进入数据流。

2.3 验证结果

发送测试请求后，检查以下项目：

请求 URL 包含预期的查询参数；
响应中的 x-amz-cf-id 等于访问日志中的 x-edge-request-id；
viewer-request-log-data 经 URL 解码后等于预期 JSON。

HTTP 200 只能说明 CloudFront 返回了响应，以上结果一致才能确认函数处理和日志投递符合预期。后续如需批量查询日志，可参阅使用 Amazon Athena 查询 CloudFront 日志。

三、使用前注意事项

调用 cf.logCustomData() 不产生额外费用；CloudFront Functions、访问日志和投递服务仍按各自方式计费。最新价格请参阅 Amazon CloudFront 定价。

方法只接受一个字符串；对象需先使用 JSON.stringify() 转换。
数据会自动进行 URL 编码，每个字段最多 800 字节，超出部分会被截断。
单次执行中多次调用时只保留最后一个值，多项数据应合并后一次写入。
未调用方法或未选择日志字段时，对应值为 – 或不会出现在输出中。
嵌入式接入点（embedded POPs）不支持自定义数据日志。
不要记录密码、Authorization 请求头、会话 Cookie、JWT、API 密钥或个人身份信息。

四、总结

cf.logCustomData() 将函数产生的数据与请求结果放入同一条 CloudFront 访问日志，适合需要结合 URI、状态码或缓存结果分析函数决策的场景。console.log() 仍适合开发和故障排查，两者用途不同。

除流量来源外，还可以记录：

A/B 测试的实验名称和分组；
鉴权结果分类，但不记录凭证；
URL 重写或源站路由策略；
机器人分类、缓存键维度或业务跟踪 ID；
查看器响应函数产生的内容版本。

实际部署时，只记录分析所需的字段，并先在测试分配中核对请求 ID 和解码后的日志值。

4.1 参考资料

➡️ 下一步行动：

相关产品：

Amazon CloudFront — 全球内容分发网络
Amazon S3 — 适用于 AI、分析和存档的几乎无限的安全对象存储
Amazon Athena — 使用 SQL 在 S3 中查询数据
Amazon CloudWatch — 可观测性工具
Amazon Kinesis — 实时流数据处理

✦ 还没有 AWS 账户？免费创建账户，即刻体验 →

相关文章：

立即咨询 → 从 AI 规划到落地实施，我们的专家团队为你全程护航。

*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。

本篇作者

AWS 架构师中心：云端创新的引领者

探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用

亚马逊AWS官方博客