使用 API Gateway REST API 设置 Amazon X-Ray - Amazon API Gateway
API Gateway 的 X-Ray 跟踪模式X-Ray 跟踪的权限在 API Gateway 控制台中启用 X-Ray 跟踪使用 API Gateway API CLI 启用 X-Ray 跟踪
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

在本节中，您可以找到有关如何使用 API Gateway REST API 设置 Amazon X-Ray 的详细信息。

API Gateway 的 X-Ray 跟踪模式

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

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 一起使用。