Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

CloudWatch 用于监控和记录 GraphQL API 数据

您可以使用 CloudWatch 指标和日志记录和调试 GraphQL API。 CloudWatch 这些工具使开发人员能够有效地监控性能，排查问题并优化 GraphQL 操作。

CloudWatch metrics 是一种工具，可提供各种指标来监控 API 性能和使用情况。这些指标分为两个主要类别：

本指南还介绍了增强指标，这些指标提供了有关解析器性能、数据来源交互和各项 GraphQL 操作的更精细数据。这些指标提供了更深入的见解，但也带来了额外的成本。

CloudWatch 日志是一种为 Graph APIs QL 启用日志功能的工具。可以在 API 的两个级别上设置日志：

您可以配置日志记录、解释日志条目以及使用日志数据进行故障排除和优化。 Amazon AppSync 提供了各种日志类型，可显示查询的执行、解析、验证和字段解析数据。

设置和配置

要在 GraphQL API 上开启自动日志功能，请使用控制台。 Amazon AppSync

手动配置 IAM 角色

如果您选择使用现有 IAM 角色，则该角色必须授予 Amazon AppSync 写入日志所需的权限 CloudWatch。要手动配置，您必须提供服务角色 ARN，以便在写入日志时 Amazon AppSync 可以代入该角色。

在 IAM 控制台中，创建一个名为 AWSAppSyncPushToCloudWatchLogsPolicy 的新策略，该策略具有以下定义：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

接下来，使用名称创建一个新角色 AWSAppSyncPushToCloudWatchLogsRole，并将新创建的策略附加到该角色。编辑该角色的信任关系以包含以下内容：

{
    "Version": "2012-10-17",
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "Service": "appsync.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
        }
    ]
}

复制角色 ARN，并在为 GraphQL AP Amazon AppSync I 设置日志时使用它。

CloudWatch 指标

您可以使用 CloudWatch 指标来监控可能导致 HTTP 状态代码或延迟的特定事件，并提供有关这些事件的警报。将发出以下指标：

实时订阅

所有指标都以一个维度发出：图表QLAPIId。这意味着所有指标都与 GraphQL API 相结合。 IDs以下指标与纯粹的 GraphQL 订阅有关： WebSockets

比较入站消息和出站消息

执行变更时会调用带有该变更的 @aws_subscribe 指令的订阅字段。每次订阅调用都会生成一条入站消息。例如，如果两个订阅字段在 @aws_subscribe 中指定了相同的变更，则调用该变更时会生成两条入站消息。

一封出站消息等于向 WebSocket 客户端传送的 5 KB 数据。例如，向 10 个客户端发送 15 KB 的数据会产生 30 条出站消息（15 KB * 10 个客户端/每条消息 5 KB = 30 条消息）。

您可以请求增加入站消息或出站消息的配额。有关更多信息，请参阅《Amazon 一般参考》中的 Amazon AppSync 端点和限额以及《服务配额用户指南》中的请求增加配额。

增强型指标

增强型指标会发出有关 API 使用情况和性能的精细数据，例如 Amazon AppSync 请求和错误计数、延迟以及缓存命中数/未命中数。所有增强型指标数据都将发送到您的 CloudWatch 账户，您可以配置要发送的数据类型。

这些指标可以在 Amazon AppSync 控制台的各个设置页面上找到。在 API 设置页面上，您可以使用增强型指标部分启用或禁用以下各项：

解析器指标行为：这些选项控制如何收集解析器的其他指标。您可以选择启用完整请求解析器指标（为请求中的所有解析器启用的指标）或每个解析器的指标（仅为配置设置为已启用的解析器启用的指标）。以下选项可用：

数据来源指标行为：这些选项控制如何收集数据来源的其他指标。您可以选择启用完整请求数据来源指标（为请求中的所有数据来源启用的指标）或每个数据来源的指标（仅为配置设置为已启用的数据来源启用的指标）。以下选项可用：

操作指标：启用 GraphQL 操作级指标。

CloudWatch 日志

您可以对任何新的或现有的 GraphQL API 配置两种类型的日志记录：请求级别和字段级别。

请求级日志

如果配置了请求级日志记录（包含详细内容），将记录以下信息：

字段级日志

如果配置了字段级日志记录，将记录以下信息：

如果您开启日志记录，则 Amazon AppSync 管理日 CloudWatch 志。该过程包括创建日志组和日志流，以及向日志流报告这些日志。

当您打开 GraphQL API 的日志记录并发出请求时， Amazon AppSync 将在该日志组下创建一个日志组和日志流。日志组以 /aws/appsync/apis/{graphql_api_id} 格式命名。在每个日志组内，日志会进一步分成多个日志流。当报告已记录的数据时，这些日志按上次事件时间排序。

每个日志事件都标有该请求的 x-amzn-RequestId。这可以帮助您筛选日志事件 CloudWatch ，以获取有关该请求的所有已记录信息。你可以 RequestId 从每个 GraphQL Amazon AppSync 请求的响应标头中获取。

字段级别日志记录配置为使用以下日志级别：

监控优势

您可以使用日志记录和指标来识别、优化 GraphQL 查询和排除其问题。例如，这些将帮助您使用针对查询中的每个字段记录的跟踪信息调试延迟问题。为了对此进行演示，假设您正在使用一个或多个嵌套在 GraphQL 查询中的解析器。L CloudWatch ogs 中的示例字段操作可能与以下内容类似：

{
    "path": [
        "singlePost",
        "authors",
        0,
        "name"
    ],
    "parentType": "Post",
    "returnType": "String!",
    "fieldName": "name",
    "startOffset": 416563350,
    "duration": 11247
}

这可能对应于 GraphQL 架构，类似于以下内容：

type Post {
  id: ID!
  name: String!
  authors: [Author]
}

type Author {
  id: ID!
  name: String!
}

type Query {
  singlePost(id:ID!): Post
}

在前面的日志结果中，path 显示运行名为 singlePost() 的查询而返回的数据中的单个项目。在该示例中，它表示第一个索引 (0) 处的 name 字段。startOffset 提供相对于 GraphQL 查询操作开始位置的偏移。duration 是解析该字段的总时间。这些值可用来排除下面这类问题：为何来自特定数据来源的数据的运行速度可能低于预期，或者特定字段是否降低了整个查询的速度等。例如，您可以选择增加 Amazon DynamoDB 表的预置吞吐量，或从查询中删除导致整体操作性能不佳的特定字段。

自 2019 年 5 月 8 日起， Amazon AppSync 将日志事件生成为完全结构化的 JSON。这可以帮助您使用 Logs Insights 和 Amazon OpenSearch 服务等 CloudWatch 日志分析服务来了解 GraphQL 请求的性能和架构字段的使用特征。例如，您可以轻松识别具有较大延迟的解析器，这可能是导致性能问题的根本原因。您还可以识别架构中最常用和最不常用的字段，并评估弃用 GraphQL 字段的影响。

冲突检测和同步日志记录

如果 Amazon AppSync API 的 CloudWatch 日志记录配置为字段解析器日志级别设置为 “全部”，则会向日志 Amazon AppSync 组发送冲突检测和解决信息。这提供了对 Amazon AppSync API 如何应对冲突的详细见解。为了帮助您解释响应，在日志中提供了以下信息：

使用令牌计数优化您的请求

对于使用少于或等于 1,500 KB 秒内存和 vCPU 时间的请求，将分配一个令牌。对于使用超过 1,500 KB 秒资源的请求，将收到额外的令牌。例如，如果请求消耗 3,350 KB 秒，则向该请求 Amazon AppSync 分配三个令牌（向上舍入到下一个整数值）。默认情况下，您账户 APIs 中每秒最多 Amazon AppSync 分配 5,000 或 10,000 个请求令牌，具体取决于其部署所在的 Amazon 区域。如果 APIs 每人平均每秒使用两个令牌，则每秒只能分别限制为 2,500 或 5,000 个请求。如果您每秒需要的令牌数多于分配的数量，您可以提交请求以增加请求令牌速率的默认配额。有关更多信息，请参阅Amazon Web Services 一般参考 指南中的Amazon AppSync 终端节点和配额以及 Servic e Quotas 用户指南中的请求增加配额。

如果每个请求的令牌数较高，则可能表明需要优化您的请求并提高 API 性能。可能增加每个请求的令牌数的因素包括：

日志大小限制

默认情况下，如果启用了日志记录， Amazon AppSync 则每次请求最多可发送 1 MB 的日志。超过此大小的日志将被截断。要减小日志大小，请为字段级日志选择 ERROR 日志记录级别并禁用 VERBOSE 日志记录，或者在不需要时完全禁用字段级日志。作为ALL日志级别的替代方案，您可以使用增强指标来获取有关特定解析器、数据源或 GraphQL 操作的指标，或者利用 AppSync 提供的日志工具仅记录必要的信息。

日志类型参考

RequestSummary

{
     "logType": "RequestSummary",
     "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
     "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4",
     "statusCode": 200,
     "latency": 242000000
}

ExecutionSummary

{
    "duration": 217406145,
    "logType": "ExecutionSummary",
    "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
    "startTime": "2019-01-01T06:06:18.956Z",
    "endTime": "2019-01-01T06:06:19.174Z",
    "parsing": {
        "startOffset": 49033,
        "duration": 34784
    },
    "version": 1,
    "validation": {
        "startOffset": 129048,
        "duration": 69126
    },
    "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4"
}

跟踪

{
    "duration": 216820346,
    "logType": "Tracing",
    "path": [
        "putItem"
    ],
    "fieldName": "putItem",
    "startOffset": 178156,
    "resolverArn": "arn:aws:appsync:us-east-1:111111111111:apis/pmo28inf75eepg63qxq4ekoeg4/types/Mutation/fields/putItem",
    "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
    "parentType": "Mutation",
    "returnType": "Item",
    "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4"
}

使用 “日志见解” 分析您的 CloudWatch 日志

以下是您可以运行的查询示例，以获取有关 GraphQL 操作的性能和运行状况的可行的见解。这些示例作为示例查询在 Logs Insight CloudWatch s 控制台中提供。在CloudWatch控制台中，选择 Lo gs Insights，选择您的 GraphQL API 的 Amazon AppSync 日志组，然后在示例Amazon AppSync 查询下选择查询。

以下查询返回使用令牌数最多的前 10 个 GraphQL 请求：

filter @message like "Tokens Consumed"
| parse @message "* Tokens Consumed: *" as requestId, tokens
| sort tokens desc
| display requestId, tokens
| limit 10

以下查询返回具有最大延迟的前 10 个解析器：

  fields resolverArn, duration
| filter logType = "Tracing"
| limit 10
| sort duration desc

以下查询返回最常调用的解析器：

  fields ispresent(resolverArn) as isRes
| stats count() as invocationCount by resolverArn
| filter isRes and logType = "Tracing"
| limit 10
| sort invocationCount desc

以下查询返回映射模板中具有最多错误的解析器：

  fields ispresent(resolverArn) as isRes
| stats count() as errorCount by resolverArn, logType
| filter isRes and (logType = "RequestMapping" or logType = "ResponseMapping") and fieldInError
| limit 10
| sort errorCount desc

以下查询返回解析器延迟统计数据：

  fields ispresent(resolverArn) as isRes
| stats min(duration), max(duration), avg(duration) as avg_dur by resolverArn
| filter isRes and logType = "Tracing"
| limit 10
| sort avg_dur desc

以下查询返回字段延迟统计数据：

  stats min(duration), max(duration), avg(duration) as avg_dur
  by concat(parentType, '/', fieldName) as fieldKey
| filter logType = "Tracing"
| limit 10
| sort avg_dur desc

可以将 CloudWatch Logs Insights 查询的结果导出到 CloudWatch 仪表板。

使用 OpenSearch 服务分析您的日志

您可以使用 Amazon S OpenSearch ervice 搜索、分析和可视化您的 Amazon AppSync 日志，以确定性能瓶颈和操作问题的根本原因。您可以识别具有最大延迟和最多错误的解析器。此外，您还可以使用 OpenSearch 仪表板创建具有强大可视化效果的仪表板。 OpenSearch 仪表板是 S OpenSearch ervice 中提供的开源数据可视化和探索工具。使用 OpenSearch 控制面板，您可以持续监控 GraphQL 操作的性能和运行状况。例如，您可以创建控制面板以可视化 GraphQL 请求的 P90 延迟，并深入了解每个解析器的 P90 延迟。

使用 S OpenSearch ervice 时，使用 “cwl*” 作为筛选器模式来搜索索 OpenSearch 引。 OpenSearch 服务使用前缀为 “cwl-” 对从 CloudWatch 日志流式传输的日志进行索引。为了将 Amazon AppSync API 日志与发送到 OpenSearch 服务的其他 CloudWatch 日志区分开来，我们建议在搜索中graphQLAPIID.keyword=YourGraphQLAPIID添加额外的筛选表达式。

日志格式迁移

2019 年 5 月 8 日当天或之后 Amazon AppSync 生成的日志事件采用完全结构化的 JSON 格式。要分析 2019 年 5 月 8 日之前的 GraphQL 请求，您可以使用示例中提供的脚本将较旧的日志迁移到完全结构化的 JSON。GitHub 如果需要在 2019 年 5 月 8 日之前使用日志格式，请使用以下设置创建支持服务单：将 Type (类型) 设置为 Account Management (账户管理)，然后将 Category (类别) 设置为 General Account Question (一般账户问题)。

您还可以使用指标筛选器将日志数据转换为数字 CloudWatch 指标，以便您可以对它们绘制图表或设置警报。 CloudWatch