使用实时日志
利用 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 定价
重要
建议您使用日志来了解内容的请求性质，而不是作为所有请求的完整描述。CloudFront 将尽力提供实时日志。特定请求的日志条目可能会在实际处理该请求之后很久才进行传输，而且极少数情况下，可能根本不会传输日志条目。当实时日志中省略了日志条目时，实时日志中的条目数将与 AWS 账单和使用率报告中出现的使用率不匹配。
创建并使用实时日志配置
要实时获取向分配发出的请求的相关信息，您可以使用实时日志配置。日志将在收到请求后的几秒钟内传送。您可以使用 AWS Command Line Interface (AWS CLI) 或 CloudFront API 在 CloudFront 控制台中创建实时日志配置。
要使用实时日志配置，请将它附加到 CloudFront 分配中的一个或多个缓存行为。
了解实时日志配置
要使用 CloudFront 实时日志，请先创建实时日志配置。实时日志配置包含有关要接收的日志字段、日志记录的采样率 以及要在其中传输日志的 Kinesis 数据流的信息。
具体而言，实时日志配置包含以下设置：
名称
用于标识实时日志配置的名称。
采样率
采样率是一个介于 1 和 100 之间的整数（含 1 和 100），用于确定作为实时日志记录发送到 Kinesis Data Streams 的查看器请求的百分比。要在实时日志中包含每个查看器请求，请指定 100 作为采样率。可以选择较低的采样率来降低成本，同时仍在实时日志中接收具有代表性的请求数据示例。
字段
每个实时日志记录中包含的字段列表。每个日志记录最多可包含 40 个字段，您可以选择接收所有可用字段，也可以选择仅接收监控和分析性能所需的字段。
以下列表包含每个字段名称和该字段中信息的说明。字段将按照它们在传输到 Kinesis Data Streams 的日志记录中的显示顺序列出。
字段 46-63 是常见的媒体客户端数据（CMCD），媒体播放器客户端可以在每次请求时将其发送到 CDN。您可以使用这些数据来了解每个请求，例如媒体类型（音频、视频）、播放速率和直播时长。只有在将这些字段发送到 CloudFront 后，它们才会显示在您的实时日志中。
-
timestamp边缘服务器完成对请求的响应的日期和时间。
-
c-ip已发出请求的查看器的 IP 地址，例如
192.0.2.183或2001:0db8:85a3::8a2e:0370:7334。如果查看器已使用 HTTP 代理或负载均衡器发送请求，则此字段的值为该代理或负载均衡器的 IP 地址。另请参阅x-forwarded-for字段。 -
s-ip为请求提供服务的 CloudFront 服务器的 IP 地址，例如
192.0.2.183或2001:0db8:85a3::8a2e:0370:7334。 -
time-to-first-byte从收到请求到写入响应的第一个字节之间的秒数（在服务器上测量）。
-
sc-status服务器响应的 HTTP 状态代码（例如
200）。 -
sc-bytes服务器在响应请求时向查看器提供的字节的总数，包括标头。对于 WebSocket 连接，这是通过连接从服务器发送到客户端的字节的总数。
-
cs-method从查看器接收的 HTTP 请求方法。
-
cs-protocol查看器请求的协议（
http、https、ws或wss）。 -
cs-host查看器在该请求的
Host标头中包含的值。如果您在对象 URL 中使用 CloudFront 域名（如 d111111abcdef8.cloudfront.net），则此字段将包含该域名。如果在您的对象 URL（例如 www.example.com）中使用的是备用域名（CNAME），则此字段将包含备用域名。 -
cs-uri-stem整个请求 URL，包括查询字符串（如果有），但不包括域名。例如，
/images/cat.jpg?mobile=true。注意
在标准日志中，该
cs-uri-stem值不包括查询字符串。 -
cs-bytes查看器包含在请求中的数据字节总数，包括标头。对于 WebSocket 连接，这是通过连接从客户端发送到服务器的字节的总数。
-
x-edge-location服务请求的边缘站点。每个边缘站点由三个字母的代码和任意分配的数字来确定（例如，DFW3）。三个字母代码通常对应邻近边缘站点的地理位置的机场的国际航空协会（IATA）机场代码。（这些缩写将来可能会更改。）
-
x-edge-request-id唯一地标识请求的不透明字符串。CloudFront 还会在
x-amz-cf-id响应标头中发送此字符串。 -
x-host-headerCloudFront 分配的域名（例如，d111111abcdef8.cloudfront.net）。
-
time-taken服务器收到查看器的请求的时间与服务器将响应的最后一个字节写入输出队列的时间之间相隔的秒数（精确至千分之一秒，例如 0.082），以服务器上测量的时间为准。从查看器的角度看，由于网络延迟和 TCP 缓冲的原因，获得完整响应的总时间将会超过该值。
-
cs-protocol-version查看器在请求中指定的 HTTP 版本。可能的值包括
HTTP/0.9、HTTP/1.0、HTTP/1.1、HTTP/2.0和HTTP/3.0。 -
c-ip-version请求的 IP 版本（IPv4 或 IPv6）。
-
cs-user-agent请求中的
User-Agent标头的值。User-Agent标头标识请求的来源，例如提交请求的设备和浏览器的类型，如果请求来自搜索引擎，则标识具体的搜索引擎。 -
cs-referer请求中的
Referer标头的值。这是发出请求的域的名称。常见引用站点包括搜索引擎、直接链接到您的对象的其他网站及您自己的网站。 -
cs-cookie请求中的
Cookie标头，包括名称/值对和关联的属性。注意
此字段被截断为 800 字节。
-
cs-uri-query请求 URL 的查询字符串部分（如果有）。
-
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。
-
-
x-forwarded-for如果查看器已使用 HTTP 代理或负载均衡器发送请求，则
c-ip字段的值为该代理或负载均衡器的 IP 地址。在本例中，此字段为发出请求的查看器的 IP 地址。此字段可以包含多个逗号分隔的 IP 地址。每个 IP 地址可以是 IPv4 地址（如192.0.2.183）或 IPv6 地址（如2001:0db8:85a3::8a2e:0370:7334）。 -
ssl-protocol如果请求使用了 HTTPS，则此字段包含查看器和服务器协商用于传输请求和响应的 SSL/TLS 协议。有关可能的值的列表，请参阅查看器和 CloudFront 之间支持的协议和密码中支持的 SSL/TLS 协议。
-
ssl-cipher如果请求使用了 HTTPS，则此字段包含查看器和服务器协商用于加密请求和响应的 SSL/TLS 密码。有关可能的值的列表，请参阅查看器和 CloudFront 之间支持的协议和密码中支持的 SSL/TLS 密码。
-
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。
-
-
fle-encrypted-fields服务器加密并转发到源的字段级加密字段的数量。CloudFront 服务器在加密数据时会将处理的请求传输到源，这样一来，即使
fle-status的值为错误，此字段也会具有值。 -
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– 在配置了字段级加密时，请求正文的长度超出允许的最大长度。
-
-
sc-content-type响应的 HTTP
Content-Type标头的值。 -
sc-content-len响应的 HTTP
Content-Length标头的值。 -
sc-range-start当响应包含 HTTP
Content-Range标头时，此字段包含范围起始值。 -
sc-range-end当响应包含 HTTP
Content-Range标头时，此字段包含范围结束值。 -
c-port查看器发出的请求的端口号。
-
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- 查看器读取导致源错误的消息时速度较慢。
-
-
-
c-country表示查看器的地理位置的国家/地区代码，由查看器的 IP 地址决定。有关国家/地区代码的列表，请参阅 ISO 3166-1 alpha-2
。 -
cs-accept-encoding查看器请求中的
Accept-Encoding标头的值。 -
cs-accept查看器请求中的
Accept标头的值。 -
cache-behavior-path-pattern标识与查看器请求匹配的缓存行为的路径模式。
-
cs-headers查看器请求中的 HTTP 标头（名称和值）。
注意
此字段被截断为 800 字节。
-
cs-header-names查看器请求中的 HTTP 标头的名称（而不是值）。
注意
此字段被截断为 800 字节。
-
cs-headers-count查看器请求中的 HTTP 标头的数量。
-
origin-fblCloudFront 与您的源之间第一字节延迟的秒数。
-
origin-lblCloudFront 与您的源之间最后一个字节延迟的秒数。
-
asn包含查看器的自治系统号 (ASN)。
-
primary-distribution-id启用持续部署后，此 ID 将标识当前分配中的哪个分配是主分配。
-
primary-distribution-dns-name启用持续部署后，此值显示与当前 CloudFront 分配相关的主域名（例如 d111111abcdef8.cloudfront.net）。
实时日志中的 CMCD 字段
有关这些字段的更多信息，请参阅 CTA 规范 Web 应用程序视频生态系统 - 通用媒体客户端数据 CTA-5004
文档。 -
cmcd-encoded-bitrate请求的音频或视频对象的编码比特率。
-
cmcd-buffer-length所请求媒体对象的缓冲区长度。
-
cmcd-buffer-starvation缓冲区是否在先前的请求和对象请求之间的某个时刻被耗尽。这可能会导致播放器处于重新缓冲状态，从而导致视频或音频播放停滞。
-
cmcd-content-id标识当前内容的唯一字符串。
-
cmcd-object-duration请求对象的播放时长（以毫秒为单位）。
-
cmcd-deadline从请求时间算起的截止日期，在这一时间，该对象的第一个样本必须可用，这样可以避免缓冲区处于欠载状态或出现其他播放问题。
-
cmcd-measured-throughput客户端和服务器之间的吞吐量，由客户端进行测量。
-
cmcd-next-object-request所请求下一个对象的相对路径。
-
cmcd-next-range-request如果下一个请求是部分对象请求，则此字符串表示要请求的字节范围。
-
cmcd-object-type所请求的当前对象的媒体类型。
-
cmcd-playback-rate如果是实时播放，则为 1；如果是倍速播放，则为 2；如果不播放，则为 0。
-
cmcd-requested-maximum-throughput请求的最大吞吐量，客户端认为足以交付资源。
-
cmcd-streaming-format定义当前请求的流媒体格式。
-
cmcd-session-id标识当前播放会话的 GUID。
-
cmcd-stream-type令牌识别区段的可用性。
v= 所有区段都可用。l= 区段会随着时间的推移而变得可用。 -
cmcd-startup如果在启动、搜索或缓冲区空事件后的恢复期间迫切需要该对象，则可包含不带值的键。
-
cmcd-top-bitrate客户端可以播放的最高比特率副本。
-
cmcd-version本规范的版本，用于解释已定义的键名和键值。如果省略此键，则客户端和服务器必须 将这些值解释为由版本 1 定义。
端点 (Kinesis Data Streams)
端点包含有关您要在其中发送实时日志的 Kinesis Data Streams 的信息。您需要提供数据流的 Amazon 资源名称（ARN）。
有关创建 Kinesis Data Streams 的更多信息，请参阅《Amazon Kinesis Data Streams 开发人员指南》中的以下主题。
创建数据流时，您需要指定分片的数量。使用以下信息可帮助您估计所需的分片数量。
估计 Kinesis 数据流的分片数
-
计算（或估算）您的 CloudFront 分配每秒钟接收的请求数。
您可以使用 CloudFront 使用情况报告
（在 CloudFront 控制台中）和 CloudFront 指标（在 CloudFront 和 Amazon CloudWatch 控制台中）来帮助您计算每秒的请求数。 -
确定单个实时日志记录的典型大小。
通常，单个日志记录约为 500 字节。一个包含所有可用字段的大型记录一般约为 1KB。
如果您不确定您的日志记录的大小，可以启用低采样率（例如 1%）的实时日志，然后使用 Kinesis Data Streams 中的监测数据计算记录的平均大小（记录总数除以总的传入字节数）。
-
在 Amazon Kinesis Data Streams 定价
页面的 AWS Pricing Calculator下方，选择立即创建您的自定义估计。 在计算器中，输入每秒的请求（记录）数。
输入单个日志记录的平均记录大小。
选择显示计算结果。
定价计算器会显示您需要的分片数量和估计成本。
IAM 角色
AWS Identity and Access Management (IAM) 角色，授予 CloudFront 向您的 Kinesis 数据流传送实时日志的权限。
使用 CloudFront 控制台创建实时日志配置时，可以选择创建新服务角色以让控制台为您创建 IAM 角色。
当您使用 AWS CloudFormation 或 CloudFront API（AWS CLI 或软件开发工具包）创建实时日志配置时，必须自行创建 IAM 角色并提供角色 ARN。要自行创建 IAM 角色，请使用以下策略。
IAM 角色信任策略
要使用以下 IAM 角色信任策略，请将 111122223333 替换为您的 AWS 账户号。此策略中的 Condition 条件元素有助于防止出现混淆代理人问题，因为 CloudFront 只能代表 AWS 账户中的分配承担此角色。
{ "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，以及用 AWS 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" ] } ] }
创建 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。
