实时日志 - Amazon CloudFront
了解实时日志配置创建和使用实时日志配置创建 Kinesis Data Streams 使用者问题排查实时日志
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

实时日志

利用 CloudFront 实时日志，您可以实时获取有关向分配发出的请求的信息（日志在收到请求后的几秒钟内传输）。您可以使用实时日志来进行监控和分析，并根据内容交付性能采取相应措施。

CloudFront 实时日志是可配置的。您可以选择：

  • 实时日志的采样率 – 即希望接收实时日志记录的请求的百分比。

  • 希望在日志记录中接收的特定字段。

  • 要接收实时日志的特定缓存行为（路径模式）。

CloudFront 实时日志将传送到 Amazon Kinesis Data Streams 中您选择的数据流。您可以构建自己的 Kinesis 数据流消费程序，或使用 Amazon Data Firehose 将日志数据发送到 Amazon Simple Storage Service（Amazon S3）、Amazon Redshift、Amazon OpenSearch Service（OpenSearch Service）或第三方日志处理服务。

CloudFront 除了收取因使用 Kinesis Data Streams 产生的费用外，还针对实时日志进行收费。有关定价的更多信息，请参阅 Amazon CloudFront 定价和 Amazon Kinesis Data Streams 定价。

重要

建议您使用日志来了解内容的请求性质，而不是作为所有请求的完整描述。CloudFront 将尽力提供实时日志。特定请求的日志条目可能会在实际处理该请求之后很久才进行传输，而且极少数情况下，可能根本不会传输日志条目。当实时日志中省略了日志条目时，实时日志中的条目数将与 Amazon 账单和使用率报告中出现的使用率不匹配。

了解实时日志配置

要使用 CloudFront 实时日志，请先创建实时日志配置。实时日志配置包含有关要接收的日志字段、日志记录的采样率 以及要在其中传输日志的 Kinesis 数据流的信息。

具体而言，实时日志配置包含以下设置：

名称

用于标识实时日志配置的名称。

采样率

采样率是一个介于 1 和 100 之间的整数（含 1 和 100），用于确定作为实时日志记录发送到 Kinesis Data Streams 的查看器请求的百分比。要在实时日志中包含每个查看器请求，请指定 100 作为采样率。可以选择较低的采样率来降低成本，同时仍在实时日志中接收具有代表性的请求数据示例。

字段

每个实时日志记录中包含的字段列表。每个日志记录最多可包含 40 个字段，您可以选择接收所有可用字段，也可以选择仅接收监控和分析性能所需的字段。

以下列表包含每个字段名称和该字段中信息的说明。字段将按照它们在传输到 Kinesis Data Streams 的日志记录中的显示顺序列出。

字段 46-63 是常见的媒体客户端数据（CMCD），媒体播放器客户端可以在每次请求时将其发送到 CDN。您可以使用这些数据来了解每个请求，例如媒体类型（音频、视频）、播放速率和直播时长。只有在将这些字段发送到 CloudFront 后，它们才会显示在您的实时日志中。

  1. timestamp

    边缘服务器完成对请求的响应的日期和时间。

  2. c-ip

    已发出请求的查看器的 IP 地址，例如 192.0.2.183 或 2001:0db8:85a3::8a2e:0370:7334。如果查看器已使用 HTTP 代理或负载均衡器发送请求，则此字段的值为该代理或负载均衡器的 IP 地址。另请参阅 x-forwarded-for 字段。

  3. time-to-first-byte

    从收到请求到写入响应的第一个字节之间的秒数（在服务器上测量）。

  4. sc-status

    服务器响应的 HTTP 状态代码（例如 200）。

  5. sc-bytes

    服务器在响应请求时向查看器提供的字节的总数，包括标头。对于 WebSocket 连接，这是通过连接从服务器发送到客户端的字节的总数。

  6. cs-method

    从查看器接收的 HTTP 请求方法。

  7. cs-protocol

    查看器请求的协议（http、https、ws 或 wss）。

  8. cs-host

    查看器在该请求的 Host 标头中包含的值。如果您在对象 URL 中使用 CloudFront 域名（如 d111111abcdef8.cloudfront.net），则此字段将包含该域名。如果在您的对象 URL（例如 www.example.com）中使用的是备用域名（CNAME），则此字段将包含备用域名。

  9. cs-uri-stem

    整个请求 URL，包括查询字符串（如果有），但不包括域名。例如，/images/cat.jpg?mobile=true。

    注意

    在标准日志中，该 cs-uri-stem 值不包括查询字符串。

  10. cs-bytes

    查看器包含在请求中的数据字节总数，包括标头。对于 WebSocket 连接，这是通过连接从客户端发送到服务器的字节的总数。

  11. x-edge-location

    服务请求的边缘站点。每个边缘站点由三个字母的代码和任意分配的数字来确定（例如，DFW3）。三个字母代码通常对应邻近边缘站点的地理位置的机场的国际航空协会（IATA）机场代码。（这些缩写将来可能会更改。）

  12. x-edge-request-id

    唯一地标识请求的不透明字符串。CloudFront 还会在 x-amz-cf-id 响应标头中发送此字符串。

  13. x-host-header

    CloudFront 分配的域名（例如，d111111abcdef8.cloudfront.net）。

  14. time-taken

    服务器收到查看器的请求的时间与服务器将响应的最后一个字节写入输出队列的时间之间相隔的秒数（精确至千分之一秒，例如 0.082），以服务器上测量的时间为准。从查看器的角度看，由于网络延迟和 TCP 缓冲的原因，获得完整响应的总时间将会超过该值。

  15. cs-protocol-version

    查看器在请求中指定的 HTTP 版本。可能的值包括 HTTP/0.9、HTTP/1.0、HTTP/1.1、HTTP/2.0 和 HTTP/3.0。

  16. c-ip-version

    请求的 IP 版本（IPv4 或 IPv6）。

  17. cs-user-agent

    请求中的 User-Agent 标头的值。User-Agent 标头标识请求的来源，例如提交请求的设备和浏览器的类型，如果请求来自搜索引擎，则标识具体的搜索引擎。

  18. cs-referer

    请求中的 Referer 标头的值。这是发出请求的域的名称。常见引用站点包括搜索引擎、直接链接到您的对象的其他网站及您自己的网站。

  19. cs-cookie

    请求中的 Cookie 标头，包括名称/值对和关联的属性。

    注意

    此字段被截断为 800 字节。

  20. cs-uri-query

    请求 URL 的查询字符串部分（如果有）。

  21. x-edge-response-result-type

    服务器在将响应返回到查看器之前如何对响应进行分类。另请参阅 x-edge-result-type 字段。可能的值包括：

    • Hit – 服务器从缓存中将对象提供给查看器。

    • RefreshHit – 服务器在缓存中找到了对象，但该对象已过期，因此，服务器联系了源，以验证缓存是否具有该对象的最新版本。

    • Miss – 缓存中的对象无法满足请求，因此，服务器将请求转发到源服务器并将结果返回到查看器。

    • LimitExceeded – 请求被拒绝，因为超出了 CloudFront 配额（以前称为限制）。

    • CapacityExceeded – 服务器返回了 503 错误，因为它在请求时没有足够的容量来服务对象。

    • Error – 通常，这意味着请求会导致客户端错误（sc-status 字段的值在 4xx 范围内）或服务器错误（sc-status 字段的值在 5xx 范围内）。

      如果 x-edge-result-type 字段的值为 Error，而此字段的值不是 Error，则客户端在下载完成前已断开连接。

    • Redirect – 服务器已根据分发设置将查看器从 HTTP 重定向到 HTTPS。

  22. x-forwarded-for

    如果查看器已使用 HTTP 代理或负载均衡器发送请求，则 c-ip 字段的值为该代理或负载均衡器的 IP 地址。在本例中，此字段为发出请求的查看器的 IP 地址。此字段可以包含多个逗号分隔的 IP 地址。每个 IP 地址可以是 IPv4 地址（如 192.0.2.183）或 IPv6 地址（如 2001:0db8:85a3::8a2e:0370:7334）。

  23. ssl-protocol

    如果请求使用了 HTTPS，则此字段包含查看器和服务器协商用于传输请求和响应的 SSL/TLS 协议。有关可能的值的列表，请参阅查看器和 CloudFront 之间支持的协议和密码中支持的 SSL/TLS 协议。

  24. ssl-cipher

    如果请求使用了 HTTPS，则此字段包含查看器和服务器协商用于加密请求和响应的 SSL/TLS 密码。有关可能的值的列表，请参阅查看器和 CloudFront 之间支持的协议和密码中支持的 SSL/TLS 密码。

  25. x-edge-result-type

    在最后一个字节离开服务器后服务器如何对响应进行分类。在某些情况下，结果类型可能会在服务器准备发送响应的时间与完成发送响应的时间之间发生变化。另请参阅 x-edge-response-result-type 字段。

    例如，在 HTTP 流中，假设服务器在缓存中发现流的一个区段。在这种情况下，此字段的值通常为 Hit。但是，如果查看器在服务器传送整个区段之前关闭连接，则最终结果类型（以及此字段的值）为 Error。

    WebSocket 连接将具有此字段的值 Miss，因为内容不可缓存，并直接通过代理回到源。

    可能的值包括：

    • Hit – 服务器从缓存中将对象提供给查看器。

    • RefreshHit – 服务器在缓存中找到了对象，但该对象已过期，因此，服务器联系了源，以验证缓存是否具有该对象的最新版本。

    • Miss – 缓存中的对象无法满足请求，因此，服务器将请求转发到源并将结果返回到查看器。

    • LimitExceeded – 请求被拒绝，因为超出了 CloudFront 配额（以前称为限制）。

    • CapacityExceeded – 服务器返回了 HTTP 503 状态代码，因为它在请求时没有足够的容量来服务对象。

    • Error – 通常，这意味着请求会导致客户端错误（sc-status 字段的值在 4xx 范围内）或服务器错误（sc-status 字段的值在 5xx 范围内）。如果 sc-status 字段的值为 200，或者如果此字段的值为 Error 且 x-edge-response-result-type 字段的值不是 Error，则表示 HTTP 请求已成功，但客户端在接收所有字节之前断开连接。

    • Redirect – 服务器已根据分发设置将查看器从 HTTP 重定向到 HTTPS。

  26. fle-encrypted-fields

    服务器加密并转发到源的字段级加密字段的数量。CloudFront 服务器在加密数据时会将处理的请求传输到源，这样一来，即使 fle-status 的值为错误，此字段也会具有值。

  27. fle-status

    在为分配配置字段级加密时，此字段包含一个指示是否已成功处理请求正文的代码。如果服务器成功处理了请求正文，加密了指定字段中的值并将请求转发到源，则此字段的值为 Processed。在这种情况下，x-edge-result-type 的值仍可以指示客户端或服务器端错误。

    此字段的可能值包括：

    • ForwardedByContentType – 由于没有配置内容类型，因此服务器将请求转发到了源，而不进行解析或加密。

    • ForwardedByQueryArgs – 由于请求包含的查询参数不在字段级加密的配置中，因此服务器将请求转发到了源，而不进行解析或加密。

    • ForwardedDueToNoProfile – 由于在字段级加密的配置中没有指定配置文件，因此服务器将请求转发到了源，而不进行解析或加密。

    • MalformedContentTypeClientError – 由于 Content-Type 标头值的格式无效，因此，服务器拒绝了该请求并向查看器返回了 HTTP 400 状态代码。

    • MalformedInputClientError – 由于请求正文的格式无效，因此服务器拒绝了该请求，并向查看器返回了 HTTP 400 状态代码。

    • MalformedQueryArgsClientError – 由于查询参数为空或格式无效，因此服务器拒绝了该请求，并向查看器返回了 HTTP 400 状态代码。

    • RejectedByContentType – 由于在字段级加密的配置中没有指定内容类型，因此服务器拒绝了该请求，并向查看器返回了 HTTP 400 状态代码。

    • RejectedByQueryArgs – 由于在字段级加密的配置中没有指定查询参数，因此服务器拒绝了该请求，并向查看器返回了 HTTP 400 状态代码。

    • ServerError – 源服务器返回了错误。

    如果请求超出字段级加密配额（以前称作限制），则此字段包含下列错误代码之一，并且服务器向查看器返回 HTTP 状态代码 400。有关字段级加密的当前配额的列表，请参对字段级加密的配额。

    • FieldLengthLimitClientError – 配置为加密的字段超出允许的最大长度。

    • FieldNumberLimitClientError – 将分配配置为加密的请求包含的字段数超过允许值。

    • RequestLengthLimitClientError – 在配置了字段级加密时，请求正文的长度超出允许的最大长度。

  28. sc-content-type

    响应的 HTTP Content-Type 标头的值。

  29. sc-content-len

    响应的 HTTP Content-Length 标头的值。

  30. sc-range-start

    当响应包含 HTTP Content-Range 标头时，此字段包含范围起始值。

  31. sc-range-end

    当响应包含 HTTP Content-Range 标头时，此字段包含范围结束值。

  32. c-port

    查看器发出的请求的端口号。

  33. x-edge-detailed-result-type

    此字段包含与 x-edge-result-type 字段相同的值，但以下情况除外：

    • 当对象从源护盾层提供给查看器时，该字段包含 OriginShieldHit。

    • 当对象不在 CloudFront 缓存中并且响应是由源请求 Lambda@Edge 函数生成时，此字段包含 MissGeneratedResponse。

    • 当 x-edge-result-type 字段的值为 Error 时，此字段包含以下值之一，其中包含有关错误的更多信息：

      • AbortedOrigin – 服务器遇到了源方面的问题。

      • ClientCommError – 由于服务器与查看器之间的通信问题，对查看器的响应已中断。

      • ClientGeoBlocked - 将分配配置为拒绝来自查看器地理位置的请求。

      • ClientHungUpRequest - 查看器在发送请求时提前停止。

      • Error – 出现错误，其错误类型不适合任何其他类别。当服务器从缓存提供错误响应时，可能会发生此类型的错误。

      • InvalidRequest – 服务器收到了来自查看器的无效请求。

      • InvalidRequestBlocked - 阻止对所请求资源的访问。

      • InvalidRequestCertificate - 分配与建立 HTTPS 连接的 SSL/TLS 证书不匹配。

      • InvalidRequestHeader - 请求包含无效的标头。

      • InvalidRequestMethod - 未将分配配置为处理所使用的 HTTP 请求方法。当分配仅支持可缓存请求时，可能会发生这种情况。

      • OriginCommError – 连接到源或从源读取数据时，请求超时。

      • OriginConnectError – 服务器无法连接到源。

      • OriginContentRangeLengthError - 源响应中的 Content-Length 标头与 Content-Range 标头中的长度不匹配。

      • OriginDnsError – 服务器无法解析源的域名。

      • OriginError - 源返回不正确的响应。

      • OriginHeaderTooBigError - 源返回的标头太大，边缘服务器无法处理。

      • OriginInvalidResponseError - 源返回无效响应。

      • OriginReadError – 服务器无法从源读取。

      • OriginWriteError – 服务器无法写入到源。

      • OriginZeroSizeObjectError - 从源发送的零大小对象会导致错误。

      • SlowReaderOriginError - 查看器读取导致源错误的消息时速度较慢。

  34. c-country

    表示查看器的地理位置的国家/地区代码，由查看器的 IP 地址决定。有关国家/地区代码的列表，请参阅 ISO 3166-1 alpha-2。

  35. cs-accept-encoding

    查看器请求中的 Accept-Encoding 标头的值。

  36. cs-accept

    查看器请求中的 Accept 标头的值。

  37. cache-behavior-path-pattern

    标识与查看器请求匹配的缓存行为的路径模式。

  38. cs-headers

    查看器请求中的 HTTP 标头（名称和值）。

    注意

    此字段被截断为 800 字节。

  39. cs-header-names

    查看器请求中的 HTTP 标头的名称（而不是值）。

    注意

    此字段被截断为 800 字节。

  40. cs-headers-count

    查看器请求中的 HTTP 标头的数量。

  41. origin-fbl

    CloudFront 与您的源之间第一字节延迟的秒数。

  42. origin-lbl

    CloudFront 与您的源之间最后一个字节延迟的秒数。

  43. asn

    包含查看器的自治系统号 (ASN)。

  44. primary-distribution-id

    启用持续部署后，此 ID 将标识当前分配中的哪个分配是主分配。

  45. primary-distribution-dns-name

    启用持续部署后，此值显示与当前 CloudFront 分配相关的主域名（例如 d111111abcdef8.cloudfront.net）。

    实时日志中的 CMCD 字段

    有关这些字段的更多信息，请参阅 CTA 规范 Web 应用程序视频生态系统 - 通用媒体客户端数据 CTA-5004 文档。

  46. cmcd-encoded-bitrate

    请求的音频或视频对象的编码比特率。

  47. cmcd-buffer-length

    所请求媒体对象的缓冲区长度。

  48. cmcd-buffer-starvation

    缓冲区是否在先前的请求和对象请求之间的某个时刻被耗尽。这可能会导致播放器处于重新缓冲状态，从而导致视频或音频播放停滞。

  49. cmcd-content-id

    标识当前内容的唯一字符串。

  50. cmcd-object-duration

    请求对象的播放时长（以毫秒为单位）。

  51. cmcd-deadline

    从请求时间算起的截止日期，在这一时间，该对象的第一个样本必须可用，这样可以避免缓冲区处于欠载状态或出现其他播放问题。

  52. cmcd-measured-throughput

    客户端和服务器之间的吞吐量，由客户端进行测量。

  53. cmcd-next-object-request

    所请求下一个对象的相对路径。

  54. cmcd-next-range-request

    如果下一个请求是部分对象请求，则此字符串表示要请求的字节范围。

  55. cmcd-object-type

    所请求的当前对象的媒体类型。

  56. cmcd-playback-rate

    如果是实时播放，则为 1；如果是倍速播放，则为 2；如果不播放，则为 0。

  57. cmcd-requested-maximum-throughput

    请求的最大吞吐量，客户端认为足以交付资源。

  58. cmcd-streaming-format

    定义当前请求的流媒体格式。

  59. cmcd-session-id

    标识当前播放会话的 GUID。

  60. cmcd-stream-type

    令牌识别区段的可用性。 v = 所有区段都可用。l = 区段会随着时间的推移而变得可用。

  61. cmcd-startup

    如果在启动、搜索或缓冲区空事件后的恢复期间迫切需要该对象，则可包含不带值的键。

  62. cmcd-top-bitrate

    客户端可以播放的最高比特率副本。

  63. cmcd-version

    本规范的版本，用于解释已定义的键名和键值。如果省略此键，则客户端和服务器必须 将这些值解释为由版本 1 定义。

端点（Kinesis 数据流）

端点包含有关您在其中发送实时日志的 Kinesis 数据流的信息。您需要提供数据流的 Amazon 资源名称（ARN）。

有关创建 Kinesis 数据流的更多信息，请参阅《Amazon Kinesis Data Streams 开发人员指南》中的以下主题。

创建数据流时，您需要指定分片的数量。使用以下信息可帮助您估计所需的分片数量。

估计 Kinesis 数据流的分片数

  1. 计算（或估算）您的 CloudFront 分配每秒钟接收的请求数。

    您可以使用 CloudFront 使用情况报告（在 CloudFront 控制台中）和 CloudFront 指标（在 CloudFront 和 Amazon CloudWatch 控制台中）来帮助您计算每秒的请求数。

  2. 确定单个实时日志记录的典型大小。

    通常，单个日志记录约为 500 字节。一个包含所有可用字段的大型记录一般约为 1KB。

    如果您不确定您的日志记录的大小，可以启用低采样率（例如 1%）的实时日志，然后使用 Kinesis Data Streams 中的监测数据计算记录的平均大小（记录总数除以总的传入字节数）。

  3. 在 Amazon Kinesis Data Streams 定价页面上的定价计算器中，输入每秒的请求（记录）数，以及单个日志记录的平均记录大小。然后选择显示计算。

    定价计算器会显示您需要的分区数量。（它还向您显示估算费用。）

    以下示例显示，对于 0.5KB 的平均记录大小和每秒 50000 个请求，您需要 50 个分区。

    Amazon Kinesis Data Streams 中的示例，其中显示了建议的分区数。
IAM 角色

Amazon Identity and Access Management (IAM) 角色，授予 CloudFront 向您的 Kinesis 数据流传送实时日志的权限。

使用 CloudFront 控制台创建实时日志配置时，可以选择创建新服务角色以让控制台为您创建 IAM 角色。

当您使用 Amazon CloudFormation 或 CloudFront API（Amazon CLI 或软件开发工具包）创建实时日志配置时，必须自行创建 IAM 角色并提供角色 ARN。要自行创建 IAM 角色，请使用以下策略。

IAM 角色信任策略

要使用以下 IAM 角色信任策略，请将 111122223333 替换为您的 Amazon Web Services 账户号。此策略中的 Condition 条件元素有助于防止出现混淆代理人问题，因为 CloudFront 只能代表 Amazon Web Services 账户中的分配承担此角色。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudfront.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333"
                }
            }
        }
    ]
}

未加密数据流的 IAM 角色权限策略

要使用以下策略，请将 arn:aws:kinesis:us-east-2:123456789012:stream/StreamName 替换为 Kinesis 数据流的 ARN。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kinesis:DescribeStreamSummary",
                "kinesis:DescribeStream",
                "kinesis:PutRecord",
                "kinesis:PutRecords"
            ],
            "Resource": [
                "arn:aws:kinesis:us-east-2:123456789012:stream/StreamName"
            ]
        }
    ]
}

已加密数据流的 IAM 角色权限策略

要使用以下策略，请用 Kinesis 数据流的 ARN 替换 arn:aws:kinesis:us-east-2:123456789012:stream/StreamName，以及用 Amazon KMS key 的 ARN 替换 arn:aws:kms:us-east-2:123456789012:key/e58a3d0b-fe4f-4047-a495-ae03cc73d486。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kinesis:DescribeStreamSummary",
                "kinesis:DescribeStream",
                "kinesis:PutRecord",
                "kinesis:PutRecords"
            ],
            "Resource": [
                "arn:aws:kinesis:us-east-2:123456789012:stream/StreamName"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": [
                "arn:aws:kms:us-east-2:123456789012:key/e58a3d0b-fe4f-4047-a495-ae03cc73d486"
            ]
        }
    ]
}

创建和使用实时日志配置

可以使用实时日志配置实时获取有关向分配发出的请求的信息（日志在收到请求后的几秒钟内传输）。您可以使用 Amazon Command Line Interface (Amazon CLI) 或 CloudFront API 在 CloudFront 控制台中创建实时日志配置。

要使用实时日志配置，请将它附加到 CloudFront 分配中的一个或多个缓存行为。

创建实时日志配置

  1. 登录 Amazon Web Services Management Console 并通过以下网址在 CloudFront 控制台中打开日志页面：https://console.amazonaws.cn/cloudfront/v4/home?#/logs。

  2. 选择实时配置选项卡。

  3. 选择创建配置。

  4. 对于名称，请输入配置名称。

  5. 对于采样率，请输入您希望接收其日志记录的请求的百分比。

  6. 对于字段，请选择要在实时日志中接收的字段。

    • 要在日志中包含所有 CMCD 字段，请选择 CMCD 所有键。

  7. 对于端点，请选择一个或多个 Kinesis 数据流来接收实时日志。

    注意

    CloudFront 实时日志将传送到您在 Kinesis Data Streams 中指定的数据流。要读取和分析实时日志，您可以构建自己的 Kinesis 数据流使用者。您也可以使用 Firehose 将日志数据发送到 Amazon S3、Amazon Redshift、Amazon OpenSearch Service 或第三方日志处理服务。

  8. 对于 IAM 角色，请选择创建新服务角色或选择现有角色。您必须具有创建 IAM 角色的权限。

  9. （可选）对于分配，请选择要附加到实时日志配置的 CloudFront 分配和缓存行为。

  10. 选择创建配置。

如果成功，控制台将显示您刚创建的实时日志配置的详细信息。

有关更多信息，请参阅 了解实时日志配置。

要使用 Amazon Command Line Interface (Amazon CLI) 创建实时日志配置，请使用 aws cloudfront create-realtime-log-config 命令。您可以使用输入文件来提供命令的输入参数，而不是将每个单独的参数指定为命令行输入。

创建实时日志配置（带输入文件的 CLI）

  1. 使用以下命令创建名为 rtl-config.yaml 的文件，其中包含 create-realtime-log-config 命令的所有输入参数。

    
aws cloudfront create-realtime-log-config --generate-cli-skeleton yaml-input > rtl-config.yaml

  2. 打开刚创建的名为 rtl-config.yaml 的文件。编辑该文件以指定所需的实时日志配置设置，然后保存该文件。请注意以下几点：

    • 对于 StreamType，唯一的有效值为 Kinesis。

    有关实时长配置设置的更多信息，请参阅了解实时日志配置。

  3. 使用以下命令通过 rtl-config.yaml 文件中的输入参数创建实时日志配置。

    
aws cloudfront create-realtime-log-config --cli-input-yaml file://rtl-config.yaml

如果成功，命令的输出将显示您刚创建的实时日志配置的详细信息。

将实时日志配置附加到现有分配（带输入文件的 CLI）

  1. 使用以下命令保存要更新的 CloudFront 分配的分配配置。将 distribution_ID 替换为分配的 ID。

    
aws cloudfront get-distribution-config --id distribution_ID --output yaml > dist-config.yaml

  2. 打开刚创建的名为 dist-config.yaml 的文件。编辑该文件，对要更新的每个缓存行为进行以下更改以使用实时日志配置。

    • 在缓存行为中，添加名为 RealtimeLogConfigArn 的字段。对于字段的值，使用要附加到此缓存行为的实时日志配置的 ARN。

    • 将 ETag 字段重命名为 IfMatch，但不更改字段的值。

    完成后保存该文件。

  3. 使用以下命令更新分配以使用实时日志配置。将 distribution_ID 替换为分配的 ID。

    
aws cloudfront update-distribution --id distribution_ID --cli-input-yaml file://dist-config.yaml

如果成功，命令的输出将显示您刚刚更新的分配的详细信息。

要使用 CloudFront API 创建实时日志配置，请使用 CreateRealtimeLogConfig。有关您在此 API 调用中指定的参数的更多信息，请参阅 了解实时日志配置 以及有关 Amazon SDK 或其他 API 客户端的 API 参考文档。

创建实时日志配置后，可以使用下列 API 调用之一将该配置附加到缓存行为：

对于这两个 API 调用，请在缓存行为内的 RealtimeLogConfigArn 字段中提供实时日志配置的 ARN。有关您在这些 API 调用中指定的其他字段的更多信息，请参阅 分配设置参考 以及有关 Amazon SDK 或其他 API 客户端的 API 参考文档。

创建 Kinesis Data Streams 使用者

要读取和分析实时日志，您可以构建或使用 Kinesis Data Streams 使用者。为 CloudFront 实时日志构建使用器时，务必了解每个实时日志记录中的字段始终以相同的顺序传递（如字段部分中所列）。确保构建您的使用器以适应此固定顺序。

例如，假设实时日志配置只包含以下三个字段：time-to-first-byte、sc-status 和 c-country。在此情况下，最后一个字段 c-country 始终是每个日志记录中的字段编号 3。但是，如果您稍后将字段添加到实时日志配置中，则记录中每个字段的位置可能会发生更改。

例如，如果您将 sc-bytes 和 time-taken 字段添加到实时日志配置，则根据字段部分中显示的顺序将这些字段插入到每个日志记录中。所有五个字段的最终顺序为 time-to-first-byte、sc-status、sc-bytes、time-taken 和 c-country。c-country 字段最初是字段编号 3，但现在为字段编号 5。如果您将字段添加到实时日志配置中，请确保您的使用器应用程序可以处理更改日志记录中位置的字段。

问题排查实时日志

创建实时日志配置后，您可能会发现未将任何记录或所有记录传输到 Kinesis Data Streams。在此情况下，您应先验证您的 CloudFront 分配是否正在接收查看器请求。如果是这样，则可以检查以下设置以继续进行问题排查。

IAM 角色权限

为了将实时日志记录传输到 Kinesis 数据流，CloudFront 将使用实时日志配置中的 IAM 角色。请确保角色信任策略和角色权限策略与 IAM 角色 中显示的策略匹配。

Kinesis Data Streams 限制

如果 CloudFront 将实时日志记录写入您的 Kinesis 数据流的速度超过流的处理速度，Kinesis Data Streams 可能会限制来自 CloudFront 的请求。在此情况下，您可以增加 Kinesis 数据流中的分片数量。每个分片最多可以支持每秒写入 1000 条记录，最大数据写入数为每秒 1 MB。