# Set up AWS X-Ray with API Gateway REST APIs
Set up AWS X-Ray

In this section you can find detailed information on how to set up [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) with API Gateway REST APIs.

**Topics**
+ [

## X-Ray tracing modes for API Gateway
](#apigateway-tracing-modes)
+ [

## Permissions for X-Ray tracing
](#set-up-xray-tracing-permissions)
+ [

## Enabling X-Ray tracing in the API Gateway console
](#apigateway-xray-console-setup)
+ [

## Enabling AWS X-Ray tracing using the API Gateway CLI
](#apigateway-xray-cli-setup)

## 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
**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 AWS 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).

## Enabling X-Ray tracing in the API Gateway console
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](https://console.aws.amazon.com/apigateway).

1. Choose your API, and then in the main navigation pane, choose **Stages**.

1. In the **Stages** pane, choose a stage.

1. In the **Logs and tracing** section, choose **Edit**.

1. To enable active X-Ray tracing, select **X-Ray tracing** to turn on X-Ray tracing.

1. 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 AWS X-Ray tracing using the API Gateway CLI
Enabling X-Ray tracing using the API Gateway API CLI

The following [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) command creates a stage with active X-Ray tracing:

```
aws apigateway create-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --deployment-id deployment-id \
    --region region \
    --tracing-enabled=true
```

The output will look like the following:

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

The following [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) command creates a stage without active X-Ray tracing:

```
aws apigateway create-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --deployment-id deployment-id \
    --region region \
    --tracing-enabled=false
```

The output will look like the following:

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

The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) turns on active X-Ray tracing for a deployed API: 

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

The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) turns off active X-Ray tracing for a deployed API: 

```
aws apigateway update-stage \
    --rest-api-id rest-api-id \
    --stage-name stage-name \
    --region region \
    --patch-operations op=replace,path=/tracingEnabled,value=false
```

The output will look like the following:

```
{
    "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 AWS CLI](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial).