使用 API Gateway REST API 设置 Amazon X-Ray - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用 API Gateway REST API 设置 Amazon X-Ray

在本节中,您可以找到有关如何使用 API Gateway REST API 设置 Amazon 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 或Amazon开发工具包更改 API 的跟踪模式。

X-Ray 跟踪的权限

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

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

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

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

  1. 通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway

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

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

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

  5. 要启用活动的 X-Ray 跟踪,请在 X-Ray 跟踪下选择启用 X-Ray 跟踪

  6. 如果需要,选择设置 X-Ray 采样规则,然后转到 X-Ray 控制台以配置采样规则

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

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

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

aws apigateway 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 阶段使用 Amazon CLI 来禁用活动的 X-Ray 跟踪,请调用 create-stage 命令,如以下示例所示:

aws apigateway 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,要使用 Amazon 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,要使用 Amazon CLI 来禁用活动的 X-Ray 跟踪,请调用 update-stage 命令,如以下示例所示:

aws apigateway update-stage \ --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 检索跟踪信息。有关更多信息,请参阅将 Amazon X-Ray API 与Amazon CLI 一起使用