Amazon API Gateway
Developer Guide

Setting Up AWS X-Ray with API Gateway

In this section you can find detailed information on how to set up AWS X-Ray with API Gateway.

X-Ray tracing modes for API Gateway

The path of a request through your application is tracked with a trace ID. A trace collects all of the segments generated by a single request, typically an HTTP GET or POST request.

There are two modes of tracing for an API Gateway API:

  • Passive: This is the default setting if you have not enabled X-Ray tracing on an API stage. This approach means that the API Gateway API is only traced if X-Ray has been enabled on an upstream service.

  • Active: When an API Gateway API stage has this setting, API Gateway automatically samples API invocation requests, based on the sampling algorithm specified by X-Ray.

    When active tracing is enabled on a stage, API Gateway creates a service-linked role in your account, if the role does not exist already. The role is named AWSServiceRoleForAPIGateway and will have the APIGatewayServiceRolePolicy managed policy attached to it. For more information about service-linked roles, see Using Service-Linked Roles.

    Note

    X-Ray applies a sampling algorithm to ensure that tracing is efficient, while still providing a representative sample of the requests that your API receives. The default sampling algorithm is 1 request per second, with 5 percent of requests sampled past that limit.

You can change the tracing mode for your API by using the API Gateway management console, the API Gateway CLI, or the API Gateway REST API.

Permissions for X-Ray Tracing

When you enable X-Ray tracing on a stage, API Gateway creates a service-linked role in your account, if the role does not exist already. The role is named AWSServiceRoleForAPIGateway and will have the APIGatewayServiceRolePolicy managed policy attached to it. For more information about service-linked roles, see Using Service-Linked Roles.

Enabling X-Ray tracing in the API Gateway console

You can use the Amazon API Gateway console to enable active tracing on an API stage.

These steps assume that you have already deployed the API to a stage.

  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. In the APIs pane, choose the API, and then choose Stages.

  3. In the Stages pane, choose the name of the stage.

  4. In the Stage Editor pane, choose the Logs/Tracing tab.

  5. To enable active X-Ray tracing, choose Enable X-Ray Tracing under X-Ray Tracing.

  6. If desired, choose Set X-Ray Sampling Rules and go to the X-Ray console to configure sampling rules.

Once you've enabled X-Ray for your API stage, you can use the X-Ray management console to view the traces and service maps.

Enabling AWS X-Ray tracing in the API Gateway CLI

To use the AWS CLI to enable active X-Ray tracing for an API stage when you create the stage, call the create-stage command as in the following example:

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

Following is example output for a successful invocation:

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

To use the AWS CLI to disable active X-Ray tracing for an API stage when you create the stage, call the create-stage command as in the following example:

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

Following is example output for a successful invocation:

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

To use the AWS CLI to enable active X-Ray tracing for an API that's already been deployed, call the update-stage command as follows:

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

To use the AWS CLI to disable active X-Ray tracing for an API that's already been deployed, call the update-stage command as in the following example:

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

Following is example output for a successful invocation:

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

Once you've enabled X-Ray for your API stage, use the X-Ray CLI to retrieve trace information. For more information, see Using the AWS X-Ray API with the AWS CLI.

Enabling AWS X-Ray tracing using the API Gateway REST API

To use the API Gateway API to enable active X-Ray tracing for an API that's already been deployed, call stage:update as follows:

PATCH /restapis/{rest-api-id}/stages/{stage-name} { "patchOperations": [{ "op": "replace", "path": "/tracingEnabled", "value: "true" }] }

Once you've enabled X-Ray for an API stage, use the X-Ray REST API to retrieve trace information. For more information, see Retrieving Traces.