Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用 API Gateway 设置 AWS X-Ray

在本节中,您可以找到有关如何借助 API Gateway 来设置 AWS X-Ray 的详细信息。

适用于 API Gateway 的 X-Ray 跟踪模式

通过跟踪 ID 来跟踪请求在您的应用程序中传输的路径。跟踪会收集单个请求(通常是 HTTP GETPOST 请求)生成的所有分段。

API Gateway API 的跟踪有两种模式:

  • 被动:如果您尚未在 API 阶段上启用 X-Ray 跟踪,则此为默认设置。此方法意味着,只有在上游服务上启用 X-Ray 后才会跟踪 API Gateway API。

  • 主动:如果 API Gateway API 阶段具有此设置,API Gateway 会自动根据 X-Ray 指定的采样算法对 API 调用请求进行采样。

    在一个阶段启用主动跟踪时,如果服务相关角色不存在,API Gateway 会在您的账户中创建该角色。该角色被命名为 AWSServiceRoleForAPIGateway,且将 APIGatewayServiceRolePolicy 托管策略附加于此。有关服务相关角色的更多信息,请参阅使用服务相关角色

    注意

    X-Ray 应用采样算法确保跟踪有效,同时为 API 所接收的请求提供代表性样本。默认的采样算法是每秒钟 1 个请求,超过此限制的请求采样 5%。

您可以使用 API Gateway 管理控制台、API Gateway CLI 或 AWS 开发工具包来更改您的 API 的跟踪模式。

X-Ray 跟踪的权限

当您在一个阶段启用 X-Ray 跟踪时,如果服务相关角色不存在,则 API Gateway 会在您的账户中创建该角色。该角色被命名为 AWSServiceRoleForAPIGateway,且将 APIGatewayServiceRolePolicy 托管策略附加于此。有关服务相关角色的更多信息,请参阅使用服务相关角色

在 API Gateway 控制台中启用 X-Ray 跟踪

您可以在 API 阶段使用 Amazon API Gateway 控制台启用活动跟踪。

这些步骤假设您已将 API 部署到阶段。

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. API 窗格中,选择 API,然后选择 Stages (阶段)

  3. Stages (阶段) 窗格中,选择该阶段的名称。

  4. Stage Editor (阶段编辑器) 窗格中,选择 Logs/Tracing (日志/跟踪) 选项卡。

  5. 要启用活动 X-Ray 跟踪,请选择 X-Ray Tracing (&xray; 跟踪) 下的 Enable X-Ray Tracing (启用 &xray; 跟踪)

  6. 如果需要,选择 Set X-Ray Sampling Rules (设置 &xray; 采样规则) 然后转到 X-Ray 控制台配置采样规则

一旦您已为 API 阶段启用了 X-Ray,则可以使用 X-Ray 管理控制台查看跟踪和服务地图。

使用 API Gateway CLI 启用 AWS X-Ray 跟踪

创建阶段时,针对 API 阶段,要使用 AWS CLI 来启用活动 X-Ray 跟踪,请调用 create-stage 命令,如以下示例所示:

aws apigateway --endpoint-url {endpoint-url} create-stage \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --deployment-id {deployment-id} \ --region {region} \ --tracing-enabled=true

下面是成功调用的示例输出:

{ "tracingEnabled": true, "stageName": {stage-name}, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": {deployment-id}, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} }

创建阶段时,针对 API 阶段,要使用 AWS CLI 来禁用活动 X-Ray 跟踪,请调用 create-stage 命令,如以下示例所示:

aws apigateway --endpoint-url {endpoint-url} create-stage \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --deployment-id {deployment-id} \ --region {region} \ --tracing-enabled=false

下面是成功调用的示例输出:

{ "tracingEnabled": false, "stageName": {stage-name}, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": {deployment-id}, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} }

针对已部署的 API,要使用 AWS CLI 来启用活动 X-Ray 跟踪,请调用 update-stage 命令,如以下示例所示:

aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --patch-operations op=replace,path=/tracingEnabled,value=true

针对已经部署的 API,要使用 AWS CLI 来禁用活动 X-Ray 跟踪,请调用 update-stage 命令,如以下示例所示:

aws apigateway update-stage \ --endpoint-url {endpoint-url} \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --region {region} \ --patch-operations op=replace,path=/tracingEnabled,value=false

下面是成功调用的示例输出:

{ "tracingEnabled": false, "stageName": {stage-name}, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": {deployment-id}, "lastUpdatedDate": 1533850033, "createdDate": 1533849811, "methodSettings": {} }

一旦您已为 API 阶段启用了 X-Ray,请使用 X-Ray CLI 检索跟踪信息。有关更多信息,请参阅 使用 AWS X-Ray API 和 AWS CLI