# Configurar o AWS X-Ray com APIs REST do API Gateway
Nesta seção, você encontrará informações detalhadas sobre como configurar o [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) com APIs REST do API Gateway.
**Topics**
+ [Modos de rastreamento do X-Ray para o API Gateway](#apigateway-tracing-modes)
+ [Permissões para rastreamento do X-Ray](#set-up-xray-tracing-permissions)
+ [Habilitar o rastreamento do X-Ray no console do API Gateway](#apigateway-xray-console-setup)
+ [Habilitar o rastreamento do AWS X-Ray usando a CLI do API Gateway](#apigateway-xray-cli-setup)
## Modos de rastreamento do X-Ray para o API Gateway
O caminho de uma solicitação pelo seu aplicativo é controlado com um ID de rastreamento. Um rastreamento coleta todos os segmentos gerados por uma única solicitação, geralmente uma solicitação HTTP `GET` ou `POST`.
Existem dois modos de rastreamento para uma API do API Gateway:
+ **Passivo**: essa será a configuração padrão se o rastreamento do X-Ray não estiver habilitado em um estágio da API. Essa abordagem significa que a API do API Gateway só é rastreada se o X-Ray estiver habilitado em um serviço upstream.
+ **Ativo**: quando um estágio da API do API Gateway tem esta configuração, o API Gateway faz a amostragem automaticamente de solicitações de invocação da API, com base no algoritmo de amostragem especificado pelo X-Ray.
Quando o rastreamento ativo estiver habilitado em um estágio, o API Gateway cria uma função vinculada ao serviço na sua conta, caso a função ainda não exista. A função é chamada de `AWSServiceRoleForAPIGateway` e terá a política gerenciada `APIGatewayServiceRolePolicy` anexada à ela. Para obter mais informações sobre funções vinculadas a um serviço, consulte [Como usar funções vinculadas a serviços](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
**nota**
O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações recebidas pela API. O algoritmo de amostragem padrão é uma solicitação por segundo, com 5% de solicitações de amostra fora do limite.
Você pode alterar o modo de rastreamento da sua API usando o console de gerenciamento do API Gateway, a CLI do API Gateway ou um SDK da AWS.
## Permissões para rastreamento do X-Ray
Quando você habilita o rastreamento do X-Ray em um estágio, o API Gateway cria uma função vinculada ao serviço na sua conta, caso a função ainda não exista. A função é chamada de `AWSServiceRoleForAPIGateway` e terá a política gerenciada `APIGatewayServiceRolePolicy` anexada à ela. Para obter mais informações sobre funções vinculadas a um serviço, consulte [Como usar funções vinculadas a serviços](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
## Habilitar o rastreamento do X-Ray no console do API Gateway
Use o console do Amazon API Gateway para habilitar o rastreamento ativo em um estágio da API.
Estas instruções presumem que você já implantou a API em um estágio.
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha a API e, no painel de navegação principal, selecione **Estágios**.
1. No painel **Estágios**, selecione um estágio.
1. Na seção **Logs e rastreamento**, selecione **Editar**.
1. Para habilitar o rastreamento ativo com X-Ray, selecione **Habilitar rastreamento com X-Ray** para ativar o rastreamento com X-Ray.
1. Escolha **Salvar alterações**.
Assim que você tiver habilitado o X-Ray para o estágio da API, use o console de gerenciamento do X-Ray para visualizar os rastreamentos e os mapas de serviço.
## Habilitar o rastreamento do AWS X-Ray usando a CLI do API Gateway
O comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) indicado a abaixo cria um estágio com o rastreamento do X-Ray ativo:
```
aws apigateway create-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--deployment-id deployment-id \
--region region \
--tracing-enabled=true
```
A saída será exibida da seguinte forma:
```
{
"tracingEnabled": true,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533849811,
"createdDate": 1533849811,
"methodSettings": {}
}
```
O comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) indicado abaixo cria um estágio sem o rastreamento do X-Ray ativo:
```
aws apigateway create-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--deployment-id deployment-id \
--region region \
--tracing-enabled=false
```
A saída será exibida da seguinte forma:
```
{
"tracingEnabled": false,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533849811,
"createdDate": 1533849811,
"methodSettings": {}
}
```
O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo ativa o rastreamento do X-Ray para uma API implantada:
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--patch-operations op=replace,path=/tracingEnabled,value=true
```
O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo desativa o rastreamento do X-Ray para uma API implantada:
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--region region \
--patch-operations op=replace,path=/tracingEnabled,value=false
```
A saída será exibida da seguinte forma:
```
{
"tracingEnabled": false,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533850033,
"createdDate": 1533849811,
"methodSettings": {}
}
```
Assim que você tiver habilitado o X-Ray para o estágio da sua API, use a CLI do X-Ray para recuperar as informações de rastreamento. Consulte mais informações em [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).