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

为 API Gateway API 配置 AWS X-Ray 采样规则

您可以使用 AWS X-Ray 控制台或软件开发工具包为您的 Amazon API Gateway API 配置采样规则。一个采样规则指定了 X-Ray 应为您的 API 记录哪些请求。通过自定义采样规则,您可以控制您记录的数据量,并即刻修改采样行为,而不修改或重新部署您的代码。

指定您的 X-Ray 采样规则之前,请阅读《X-Ray 开发人员指南》中的以下主题:

针对 API Gateway API 的 X-Ray 采样规则选项值

以下 X-Ray 采样选项与 API Gateway 相关。字符串值可以使用通配符来匹配单个字符 (?) 或零或多个字符 (*)。有关更多详细信息,包括如何使用容器速率设置的详细说明,请参阅 AWS X-Ray 控制台中的配置采样规则

  • 规则名称(字符串) — 一个唯一的规则名称。

  • 优先级(1 和 9999 之间的整数) — 采样规则的优先级。服务按优先级的上升顺序评估规则,并与匹配的第一条规则进行抽样决策。

  • 容器(非负整数) — 在应用固定速率之前,每秒与仪器匹配的固定请求数。该容器不由服务直接使用,但适用于所有使用该规则的服务。

  • 速率(0 到 100 之间的数字) — 容器耗尽后,与仪器相匹配的请求百分比。

  • 服务名称(字符串) — API 阶段名称,形式为 {api-name}/{stage-name}。例如,如果您要将 PetStore 示例 API 部署到名为 test 的阶段,则要在您的采样规则中指定的 Service name (服务名称) 值应为 pets/test

  • 服务类型(字符串) — 对于 API Gateway API,可以指定 AWS::ApiGateway::StageAWS::ApiGateway::*

  • 主机(字符串) — HTTP 主机标头中的主机名。请将 * 设置为匹配所有的主机名。或者,您可以指定完整的或部分主机名进行匹配,例如 api.example.com*.example.com

  • 资源 ARN(字符串)— API 阶段的 ARN,格式为 arn:aws:execute-api:{region}:{account-id}:{api-id}/{stage-name},例如 arn:aws:execute-api:us-east-1:123456789012:qsxrty/test

    该阶段名可以从控制台或 API Gateway CLI 或 API 获取。有关 ARN 格式的更多信息,请参阅 Amazon Web Services 一般参考

  • HTTP 方法(字符串) — 要采样的方法,例如 GET

  • URL 路径(字符串) — API Gateway 不支持此选项。

  • (可选)属性(密钥和值) — 来自原始 HTTP 请求的标头,例如 ConnectionContent-LengthContent-Type。每个属性值的长度最多为 32 个字符。

X-Ray 采样规则示例

采样规则示例 #1

此规则在 test 阶段针对 testxray API 所有的 GET 请求采样。

  • 规则名称 — test-sampling

  • 优先级 — 17

  • 容器大小 — 10

  • 固定速率 — 10

  • 服务名称 — testxray/test

  • 服务类型 — AWS::ApiGateway::Stage

  • HTTP 方法 — GET

  • 资源 ARN — *

  • 主机 — *

采样规则示例 #2

此规则在 prod 阶段针对 testxray API 的所有请求采样。

  • 规则名称 — prod-sampling

  • 优先级 — 478

  • 容器大小 — 1

  • 固定速率 — 60

  • 服务名称 — testxray/prod

  • 服务类型 — AWS::ApiGateway::Stage

  • HTTP 方法 — *

  • 资源 ARN — *

  • 主机 — *

  • 属性{}