Set up Amazon X-Ray with API Gateway REST APIs
In this section you can find detailed information on how to set up Amazon X-Ray with API Gateway REST APIs.
Topics
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 theAPIGatewayServiceRolePolicy
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 an Amazon SDK.
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.
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway
. -
Choose your API, and then in the main navigation pane, choose Stages.
-
In the Stages pane, choose a stage.
-
In the Logs and tracing section, choose Edit.
-
To enable active X-Ray tracing, select X-Ray tracing to turn on X-Ray tracing.
Choose Save changes.
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 Amazon X-Ray tracing using the API Gateway CLI
To use the Amazon 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 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 Amazon 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 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 Amazon 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 Amazon 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 \ --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 X-Ray API with the Amazon CLI.