# 使用实时访问日志
利用 CloudFront 实时访问日志，您可以实时获取有关向分配发出的请求的信息（日志在收到请求后的几秒钟内传输）。您可以使用实时访问日志来进行监控和分析，并根据内容交付性能采取相应措施。
CloudFront 实时访问日志是可配置的。您可以选择：
+ 实时日志的*采样率*，即希望接收实时访问日志记录的请求的百分比。
+ 希望在日志记录中接收的特定字段。
+ 要接收实时日志的特定缓存行为（路径模式）。
CloudFront 实时访问日志将传送到 Amazon Kinesis Data Streams 中您选择的数据流。您可以构建自己的 [Kinesis 数据流消费程序](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-consumers.html)，或使用 Amazon Data Firehose 将日志数据发送到 Amazon Simple Storage Service（Amazon S3）、Amazon Redshift、Amazon OpenSearch Service（OpenSearch Service）或第三方日志处理服务。
CloudFront 除了收取因使用 Kinesis Data Streams 产生的费用外，还针对实时访问日志进行收费。有关定价的更多信息，请参阅 [Amazon CloudFront 定价](https://aws.amazon.com/cloudfront/pricing/)和 [Amazon Kinesis Data Streams 定价](https://aws.amazon.com/kinesis/data-streams/pricing/)。
**重要**
建议您使用日志来了解内容的请求性质，而不是作为所有请求的完整描述。CloudFront 将尽力提供实时访问日志。特定请求的日志条目可能会在实际处理该请求之后很久才进行传输，而且极少数情况下，可能根本不会传输日志条目。当实时访问日志中省略了日志条目时，实时访问日志中的条目数将与 AWS 账单和使用情况报告中显示的使用情况不匹配。
**Topics**
+ [创建并使用实时访问日志配置](#create-real-time-log-config)
+ [了解实时访问日志配置](#understand-real-time-log-config)
+ [创建 Kinesis Data Streams 使用者](#real-time-log-consumer-guidance)
+ [实时访问日志问题排查](#real-time-log-troubleshooting)
## 创建并使用实时访问日志配置
要实时获取向分配发出的请求的相关信息，您可以使用实时访问日志配置。日志将在收到请求后的几秒钟内传送。您可以在 CloudFront 控制台中、使用 AWS Command Line Interface（AWS CLI）或 CloudFront API 创建实时访问日志配置。
要使用实时访问日志配置，请将它附加到 CloudFront 分配中的一个或多个缓存行为。
------
#### [ Console ]
**创建实时访问日志配置**
1. 登录 AWS 管理控制台 并通过以下网址在 CloudFront 控制台中打开**日志**页面：[https://console.aws.amazon.com/cloudfront/v4/home?#/logs](https://console.aws.amazon.com/cloudfront/v4/home?#/logs)。
1. 选择**实时配置**选项卡。
1. 选择**创建配置**。
1. 对于**名称**，请输入配置名称。
1. 对于**采样率**，请输入您希望接收其日志记录的请求的百分比。
1. 对于**字段**，请选择要在实时访问日志中接收的字段。
+ 要在日志中包含所有 [CMCD 字段](#CMCD-real-time-logging-fields)，请选择 **CMCD 所有键**。
1. 对于**端点**，请选择一个或多个 Kinesis Data Streams 来接收实时访问日志。
**注意**
CloudFront 实时访问日志将传送到您在 Kinesis Data Streams 中指定的数据流。要读取和分析实时访问日志，您可以构建自己的 Kinesis 数据流使用者。您也可以使用 Firehose 将日志数据发送到 Amazon S3、Amazon Redshift、Amazon OpenSearch Service 或第三方日志处理服务。
1. 对于 **IAM 角色**，请选择**创建新服务角色**或选择现有角色。您必须具有创建 IAM 角色的权限。
1. （可选）对于**分配**，请选择要附加到实时访问日志配置的 CloudFront 分配和缓存行为。
1. 选择**创建配置**。
如果成功，控制台将显示您刚创建的实时访问日志配置的详细信息。
有关更多信息，请参阅 [了解实时访问日志配置](#understand-real-time-log-config)。
------
#### [ AWS CLI ]
要使用 AWS 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
```
1. 打开刚创建的名为 `rtl-config.yaml` 的文件。编辑该文件以指定所需的实时访问日志配置设置，然后保存该文件。请注意以下几点：
+ 对于 `StreamType`，唯一的有效值为 `Kinesis`。
有关实时长配置设置的更多信息，请参阅[了解实时访问日志配置](#understand-real-time-log-config)。
1. 通过以下命令，使用 `rtl-config.yaml` 文件中的输入参数创建实时访问日志配置。
```
aws cloudfront create-realtime-log-config --cli-input-yaml file://rtl-config.yaml
```
如果成功，命令的输出将显示您刚创建的实时访问日志配置的详细信息。
**将实时访问日志配置附加到现有分配（CLI 及输入文件）**
1. 使用以下命令保存要更新的 CloudFront 分配的分配配置。将 *distribution\$1ID* 替换为分配的 ID。
```
aws cloudfront get-distribution-config --id distribution_ID --output yaml > dist-config.yaml
```
1. 打开刚创建的名为 `dist-config.yaml` 的文件。编辑该文件，针对要进行更新来使用实时访问日志配置的每个缓存行为，进行以下更改。
+ 在缓存行为中，添加名为 `RealtimeLogConfigArn` 的字段。对于字段的值，使用要附加到此缓存行为的实时访问日志配置的 ARN。
+ 将 `ETag` 字段重命名为 `IfMatch`，但不更改字段的值。
完成后保存该文件。
1. 使用以下命令更新分配以使用实时访问日志配置。将 *distribution\$1ID* 替换为分配的 ID。
```
aws cloudfront update-distribution --id distribution_ID --cli-input-yaml file://dist-config.yaml
```
如果成功，命令的输出将显示您刚刚更新的分配的详细信息。
------
#### [ API ]
要使用 CloudFront API 创建实时访问日志配置，请使用 [CreateRealtimeLogConfig](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateRealtimeLogConfig.html) API 操作。有关您在此 API 调用中指定的参数的更多信息，请参阅 [了解实时访问日志配置](#understand-real-time-log-config) 以及有关 AWS SDK 或其他 API 客户端的 API 参考文档。
创建实时访问日志配置后，您可以使用下列 API 操作之一将该配置附加到缓存行为：
+ 要将该配置附加到现有分配中的缓存行为，请使用 [UpdateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateDistribution.html)。
+ 要将该配置附加到新分配中的缓存行为，请使用 [CreateDistribution](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateDistribution.html)。
对于这两个 API 操作，请在缓存行为内的 `RealtimeLogConfigArn` 字段中提供实时访问日志配置的 ARN。有关您在这些 API 调用中指定的其他字段的更多信息，请参阅 [所有分配设置参考](distribution-web-values-specify.md) 以及有关 AWS SDK 或其他 API 客户端的 API 参考文档。
------
## 了解实时访问日志配置
要使用 CloudFront 实时访问日志，请先创建实时访问日志配置。实时访问日志配置包含有关要接收的日志字段、日志记录的*采样率*以及要在其中传输日志的 Kinesis 数据流的信息。
具体而言，实时访问日志配置包含以下设置：
**Contents**
+ [名称](#real-time-logs-name)
+ [采样率](#real-time-logs-sampling-rate)
+ [字段](#real-time-logs-fields)
+ [端点 (Kinesis Data Streams)](#real-time-logs-endpoint)
+ [IAM 角色](#real-time-logs-IAM)
### 名称
用于标识实时访问日志配置的名称。
### 采样率
采样率是一个介于 1 和 100 之间的整数（含 1 和 100），用于确定作为实时访问日志记录发送到 Kinesis Data Streams 的查看器请求的百分比。要在实时访问日志中包含所有查看器请求，请指定 100 作为采样率。您可以选择较低的采样率来降低成本，同时仍在实时访问日志中接收具有代表性的请求数据样本。
### 字段
每个实时访问日志记录中包含的字段列表。每个日志记录最多可包含 40 个字段，您可以选择接收所有可用字段，也可以选择仅接收监控和分析性能所需的字段。
以下列表包含每个字段名称和该字段中信息的说明。字段将按照它们在传输到 Kinesis Data Streams 的日志记录中的显示顺序列出。
字段 46-63 是[常见的媒体客户端数据（CMCD）](#CMCD-real-time-logging-fields)，媒体播放器客户端可以在每次请求时将其发送到 CDN。您可以使用这些数据来了解每个请求，例如媒体类型（音频、视频）、播放速率和直播时长。只有在将这些字段发送到 CloudFront 后，它们才会显示在您的实时访问日志中。
1. **`timestamp`**
边缘服务器完成对请求的响应的日期和时间。
1. **`c-ip`**
已发出请求的查看器的 IP 地址，例如 `192.0.2.183` 或 `2001:0db8:85a3::8a2e:0370:7334`。如果查看器已使用 HTTP 代理或负载均衡器发送请求，则此字段的值为该代理或负载均衡器的 IP 地址。另请参阅 `x-forwarded-for` 字段。
1. **`s-ip`**
为请求提供服务的 CloudFront 服务器的 IP 地址，例如 `192.0.2.183` 或 `2001:0db8:85a3::8a2e:0370:7334`。
1. **`time-to-first-byte`**
从收到请求到写入响应的第一个字节之间的秒数（在服务器上测量）。
1. **`sc-status`**
服务器响应的 HTTP 状态代码（例如 `200`）。
1. **`sc-bytes`**
服务器在响应请求时向查看器提供的字节的总数，包括标头。对于 WebSocket 和 gRPC 连接，这是通过连接从服务器发送到客户端的字节的总数。
1. **`cs-method`**
从查看器接收的 HTTP 请求方法。
1. **`cs-protocol`**
查看器请求的协议（`http`、`https`、`grpcs`、`ws` 或 `wss`）。
1. **`cs-host`**
查看器在该请求的 `Host` 标头中包含的值。如果您在对象 URL 中使用 CloudFront 域名（如 d111111abcdef8.cloudfront.net），则此字段将包含该域名。如果在您的对象 URL（例如 www.example.com）中使用的是备用域名（CNAME），则此字段将包含备用域名。
1. **`cs-uri-stem`**
整个请求 URL，包括查询字符串（如果有），但不包括域名。例如：`/images/cat.jpg?mobile=true`。
**注意**
在[标准日志](AccessLogs.md)中，该 `cs-uri-stem` 值不包括查询字符串。
1. **`cs-bytes`**
查看器包含在请求中的数据字节总数，包括标头。对于 WebSocket 和 gRPC 连接，这是通过连接从客户端发送到服务器的字节的总数。
1. **`x-edge-location`**
服务请求的边缘站点。每个边缘站点由三个字母的代码和任意分配的数字来确定（例如，DFW3）。三个字母代码通常对应邻近边缘站点的地理位置的机场的国际航空协会（IATA）机场代码。（这些缩写将来可能会更改。）
1. **`x-edge-request-id`**
唯一地标识请求的不透明字符串。CloudFront 还会在 `x-amz-cf-id` 响应标头中发送此字符串。
1. **`x-host-header`**
CloudFront 分配的域名（例如，d111111abcdef8.cloudfront.net）。
1. **`time-taken`**
服务器收到查看器的请求的时间与服务器将响应的最后一个字节写入输出队列的时间之间相隔的秒数（精确至千分之一秒，例如 0.082），以服务器上测量的时间为准。从查看器的角度看，由于网络延迟和 TCP 缓冲的原因，获得完整响应的总时间将会超过该值。
1. **`cs-protocol-version`**
查看器在请求中指定的 HTTP 版本。可能的值包括 `HTTP/0.9`、`HTTP/1.0`、`HTTP/1.1`、`HTTP/2.0` 和 `HTTP/3.0`。
1. **`c-ip-version`**
请求的 IP 版本（IPv4 或 IPv6）。
1. **`cs-user-agent`**
请求中的 `User-Agent` 标头的值。`User-Agent` 标头标识请求的来源，例如提交请求的设备和浏览器的类型，如果请求来自搜索引擎，则标识具体的搜索引擎。
1. **`cs-referer`**
请求中的 `Referer` 标头的值。这是发出请求的域的名称。常见引用站点包括搜索引擎、直接链接到您的对象的其他网站及您自己的网站。
1. **`cs-cookie`**
请求中的 `Cookie` 标头，包括名称/值对和关联的属性。
**注意**
此字段被截断为 800 字节。
1. **`cs-uri-query`**
请求 URL 的查询字符串部分（如果有）。
1. **`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。
+ `LambdaExecutionError`：由于关联格式错误、函数超时、AWS 依赖关系问题或其它正式发布问题，与分配关联的 Lambda@Edge 函数未完成。
1. **`x-forwarded-for`**
如果查看器已使用 HTTP 代理或负载均衡器发送请求，则 `c-ip` 字段的值为该代理或负载均衡器的 IP 地址。在本例中，此字段为发出请求的查看器的 IP 地址。此字段可以包含多个逗号分隔的 IP 地址。每个 IP 地址可以是 IPv4 地址（如 `192.0.2.183`）或 IPv6 地址（如 `2001:0db8:85a3::8a2e:0370:7334`）。
1. **`ssl-protocol`**
如果请求使用了 HTTPS，则此字段包含查看器和服务器协商用于传输请求和响应的 SSL/TLS 协议。有关可能的值的列表，请参阅[查看器和 CloudFront 之间支持的协议和密码](secure-connections-supported-viewer-protocols-ciphers.md)中支持的 SSL/TLS 协议。
1. **`ssl-cipher`**
如果请求使用了 HTTPS，则此字段包含查看器和服务器协商用于加密请求和响应的 SSL/TLS 密码。有关可能的值的列表，请参阅[查看器和 CloudFront 之间支持的协议和密码](secure-connections-supported-viewer-protocols-ciphers.md)中支持的 SSL/TLS 密码。
1. **`x-edge-result-type`**
在最后一个字节离开服务器后服务器如何对响应进行分类。在某些情况下，结果类型可能会在服务器准备发送响应的时间与完成发送响应的时间之间发生变化。另请参阅 `x-edge-response-result-type` 字段。
例如，在 HTTP 流中，假设服务器在缓存中发现流的一个区段。在这种情况下，此字段的值通常为 `Hit`。但是，如果查看器在服务器传送整个区段之前关闭连接，则最终结果类型（以及此字段的值）为 `Error`。
WebSocket 和 gRPC 连接的此字段的值为 `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。
+ `LambdaExecutionError`：由于关联格式错误、函数超时、AWS 依赖关系问题或其它正式发布问题，与分配关联的 Lambda@Edge 函数未完成。
1. **`fle-encrypted-fields`**
服务器加密并转发到源的[字段级加密](field-level-encryption.md)字段的数量。CloudFront 服务器在加密数据时会将处理的请求传输到源，这样一来，即使 `fle-status` 的值为错误，此字段也会具有值。
1. **`fle-status`**
在为分配配置[字段级加密](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/field-level-encryption.html)时，此字段包含一个指示是否已成功处理请求正文的代码。如果服务器成功处理了请求正文，加密了指定字段中的值并将请求转发到源，则此字段的值为 `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。有关字段级加密的当前配额的列表，请参[对字段级加密的配额](cloudfront-limits.md#limits-field-level-encryption)。
+ `FieldLengthLimitClientError` – 配置为加密的字段超出允许的最大长度。
+ `FieldNumberLimitClientError` – 将分配配置为加密的请求包含的字段数超过允许值。
+ `RequestLengthLimitClientError` – 在配置了字段级加密时，请求正文的长度超出允许的最大长度。
1. **`sc-content-type`**
响应的 HTTP `Content-Type` 标头的值。
1. **`sc-content-len`**
响应的 HTTP `Content-Length` 标头的值。
1. **`sc-range-start`**
当响应包含 HTTP `Content-Range` 标头时，此字段包含范围起始值。
1. **`sc-range-end`**
当响应包含 HTTP `Content-Range` 标头时，此字段包含范围结束值。
1. **`c-port`**
查看器发出的请求的端口号。
1. **`x-edge-detailed-result-type`**
此字段包含与 `x-edge-result-type` 字段相同的值，但以下情况除外：
+ 当对象从[源护盾](origin-shield.md)层提供给查看器时，该字段包含 `OriginShieldHit`。
+ 当对象不在 CloudFront 缓存中并且响应是由[源请求 Lambda@Edge 函数](lambda-at-the-edge.md)生成时，此字段包含 `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` - 查看器读取导致源错误的消息时速度较慢。
1. **`c-country`**
表示查看器的地理位置的国家/地区代码，由查看器的 IP 地址决定。有关国家/地区代码的列表，请参阅 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。
1. **`cs-accept-encoding`**
查看器请求中的 `Accept-Encoding` 标头的值。
1. **`cs-accept`**
查看器请求中的 `Accept` 标头的值。
1. **`cache-behavior-path-pattern`**
标识与查看器请求匹配的缓存行为的路径模式。
1. **`cs-headers`**
查看器请求中的 HTTP 标头（名称和值）。
**注意**
此字段被截断为 800 字节。
1. **`cs-header-names`**
查看器请求中的 HTTP 标头的名称（而不是值）。
**注意**
此字段被截断为 800 字节。
1. **`cs-headers-count`**
查看器请求中的 HTTP 标头的数量。
1. **`primary-distribution-id`**
启用持续部署后，此 ID 将标识当前分配中的哪个分配是主分配。
1. **`primary-distribution-dns-name`**
启用持续部署后，此值显示与当前 CloudFront 分配相关的主域名（例如 d111111abcdef8.cloudfront.net）。
1. **`origin-fbl`**
CloudFront 与您的源之间第一字节延迟的秒数。
1. **`origin-lbl`**
CloudFront 与您的源之间最后一个字节延迟的秒数。
1. **`asn`**
包含查看器的自治系统号 (ASN)。
1.
**实时访问日志中的 CMCD 字段**
有关这些字段的更多信息，请参阅 [CTA 规范 Web 应用程序视频生态系统 - 通用媒体客户端数据 CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf) 文档。
1. **`cmcd-encoded-bitrate`**
请求的音频或视频对象的编码比特率。
1. **`cmcd-buffer-length`**
所请求媒体对象的缓冲区长度。
1. **`cmcd-buffer-starvation`**
缓冲区是否在先前的请求和对象请求之间的某个时刻被耗尽。这可能会导致播放器处于重新缓冲状态，从而导致视频或音频播放停滞。
1. **`cmcd-content-id`**
标识当前内容的唯一字符串。
1. **`cmcd-object-duration`**
请求对象的播放时长（以毫秒为单位）。
1. **`cmcd-deadline`**
从请求时间算起的截止日期，在这一时间，该对象的第一个样本必须可用，这样可以避免缓冲区处于欠载状态或出现其他播放问题。
1. **`cmcd-measured-throughput`**
客户端和服务器之间的吞吐量，由客户端进行测量。
1. **`cmcd-next-object-request`**
所请求下一个对象的相对路径。
1. **`cmcd-next-range-request`**
如果下一个请求是部分对象请求，则此字符串表示要请求的字节范围。
1. **`cmcd-object-type`**
所请求的当前对象的媒体类型。
1. **`cmcd-playback-rate`**
如果是实时播放，则为 1；如果是倍速播放，则为 2；如果不播放，则为 0。
1. **`cmcd-requested-maximum-throughput`**
请求的最大吞吐量，客户端认为足以交付资源。
1. **`cmcd-streaming-format`**
定义当前请求的流媒体格式。
1. **`cmcd-session-id`**
标识当前播放会话的 GUID。
1. **`cmcd-stream-type`**
令牌识别区段的可用性。 `v` = 所有区段都可用。`l` = 区段会随着时间的推移而变得可用。
1. **`cmcd-startup`**
如果在启动、搜索或缓冲区空事件后的恢复期间迫切需要该对象，则可包含不带值的键。
1. **`cmcd-top-bitrate`**
客户端可以播放的最高比特率副本。
1. **`cmcd-version`**
本规范的版本，用于解释已定义的键名和键值。如果省略此键，则客户端和服务器*必须* 将这些值解释为由版本 1 定义。
1. **`r-host`**
此字段针对源请求发送，表示用于提供对象的原始服务器的域。出现错误时，您可以使用此字段来查找上次尝试的源，例如：`cd8jhdejh6a.mediapackagev2.us-east-1.amazonaws.com`。
1. **`sr-reason`**
此字段提供选择该源的原因。当对主源发出的请求成功时，此字段为空。
如果发生源失效转移，则该字段将包含导致失效转移的 HTTP 错误代码，例如 `Failover:403` 或 `Failover:502`。出现源失效转移时，如果重试的请求也失败并且您没有配置自定义错误页面，则 `r-status` 指示第二个源的响应。但是，如果您配置了自定义错误页面以及源失效转移，则在请求失败并且改为返回自定义错误页面时，这将包含第二个源的响应。
如果没有发生源失效转移，但选择了媒体质量感知弹性（MQAR）源，则会将其记录为 `MediaQuality`。有关更多信息，请参阅 [媒体质量感知弹性](media-quality-score.md)。
1. **`x-edge-mqcs`**
此字段表示在 MediaPackage v2 的 CMSD 响应标头中，CloudFront 检索到的媒体分段的媒体质量置信度分数（MQCS，Media Quality Confidence Score，范围：0 到 100）。对与启用 MQAR 的源组的缓存行为相匹配的请求，此字段可用。在源请求之外，CloudFront 还会为从其缓存中提供的媒体分段记录此字段。有关更多信息，请参阅 [媒体质量感知弹性](media-quality-score.md)。
1. **`distribution-tenant-id`**
分配租户的 ID。
1. **`connection-id`**
TLS 连接的唯一标识符。
您必须先为分配启用 mTLS，之后才能获取此字段的信息。有关更多信息，请参阅 [CloudFront 的双向 TLS 身份验证（查看器 mTLS）源双向 TLS 与 CloudFront 结合使用](mtls-authentication.md)。
### 端点 (Kinesis Data Streams)
端点包含有关您要在其中发送实时日志的 Kinesis Data Streams 的信息。您需要提供数据流的 Amazon 资源名称（ARN）。
有关创建 Kinesis Data Streams 的更多信息，请参阅《Amazon Kinesis Data Streams 开发人员指南》**中的以下主题。
+ [Creating and managing streams](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html)
+ [Perform basic Kinesis Data Streams operations using the AWS CLI](https://docs.aws.amazon.com/streams/latest/dev/fundamental-stream.html)
+ [Creating a stream](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html)（使用适用于 Java 的 AWS SDK）
创建数据流时，您需要指定分片的数量。使用以下信息可帮助您估计所需的分片数量。
**估计 Kinesis 数据流的分片数**
1. 计算（或估算）您的 CloudFront 分配每秒钟接收的请求数。
您可以使用 [CloudFront 使用情况报告](https://console.aws.amazon.com/cloudfront/v4/home#/usage)（在 CloudFront 控制台中）和 [CloudFront 指标](viewing-cloudfront-metrics.md#monitoring-console.distributions)（在 CloudFront 和 Amazon CloudWatch 控制台中）来帮助您计算每秒的请求数。
1. 确定单个实时访问日志记录的典型大小。
通常，单个日志记录约为 500 字节。一个包含所有可用字段的大型记录一般约为 1KB。
如果您不确定您的日志记录的大小，可以启用低采样率（例如 1%）的实时日志，然后使用 Kinesis Data Streams 中的监测数据计算记录的平均大小（记录总数除以总的传入字节数）。
1. 在 [Amazon Kinesis Data Streams 定价](https://aws.amazon.com/kinesis/data-streams/pricing/)页面的 AWS 定价计算器下方，选择**立即创建您的自定义估计**。
+ 在计算器中，输入每秒的请求（记录）数。
+ 输入单个日志记录的平均记录大小。
+ 选择**显示计算结果**。
定价计算器会显示您需要的分片数量和估计成本。
### IAM 角色
AWS Identity and Access Management（IAM）角色，授予 CloudFront 向您的 Kinesis 数据流传送实时访问日志的权限。
使用 CloudFront 控制台创建实时访问日志配置时，可以选择**创建新服务角色**以让控制台为您创建 IAM 角色。
当您使用 AWS CloudFormation 或 CloudFront API（AWS CLI 或 SDK）创建实时访问日志配置时，必须自行创建 IAM 角色并提供角色 ARN。要自行创建 IAM 角色，请使用以下策略。
**IAM 角色信任策略**
要使用以下 IAM 角色信任策略，请将 *111122223333* 替换为您的 AWS 账户号。此策略中的 `Condition` 条件元素有助于防止出现[混淆代理人问题](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)，因为 CloudFront 只能代表 AWS 账户中的分配承担此角色。
------
#### [ JSON ]
****
```
{
"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。
------
#### [ JSON ]
****
```
{
"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*。
------
#### [ JSON ]
****
```
{
"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 实时日志构建使用者时，务必了解每个实时访问日志记录中的字段始终以相同的顺序传递，如[字段](#real-time-logs-fields)部分中所列。确保构建您的使用器以适应此固定顺序。
例如，假设实时访问日志配置只包含以下三个字段：`time-to-first-byte`、`sc-status` 和 `c-country`。在此情况下，最后一个字段 `c-country` 始终是每个日志记录中的字段编号 3。但是，如果您稍后将字段添加到实时访问日志配置中，则记录中每个字段的位置可能会发生更改。
例如，如果您将 `sc-bytes` 和 `time-taken` 字段添加到实时访问日志配置，则这些字段将根据[字段](#real-time-logs-fields)部分中显示的顺序插入到每个日志记录中。所有五个字段的最终顺序为 `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 角色](#real-time-logs-IAM) 中显示的策略匹配。
**Kinesis Data Streams 限制**
如果 CloudFront 将实时访问日志记录写入您的 Kinesis 数据流的速度超过流的处理速度，Kinesis Data Streams 可能会限制来自 CloudFront 的请求。在此情况下，您可以增加 Kinesis 数据流中的分片数量。每个分片最多可以支持每秒写入 1000 条记录，最大数据写入数为每秒 1 MB。