# Configuración de AWS X-Ray con las API de REST de API Gateway
En esta sección, encontrará información detallada acerca de cómo configurar [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) con las API REST de API Gateway.
**Topics**
+ [Modos de rastreo de X-Ray para API Gateway](#apigateway-tracing-modes)
+ [Permisos para el rastreo de X-Ray](#set-up-xray-tracing-permissions)
+ [Activación del rastreo de X-Ray en la consola de API Gateway](#apigateway-xray-console-setup)
+ [Habilitación del rastreo de AWS X-Ray mediante la CLI de API Gateway](#apigateway-xray-cli-setup)
## Modos de rastreo de X-Ray para API Gateway
La ruta que recorre una solicitud a través de la aplicación se rastrea mediante un ID de rastro. Un rastro recopila todos los segmentos generados por una única solicitud, por lo general, una solicitud HTTP o `GET` `POST`.
Existen dos modos de rastreo para una API de API Gateway:
+ **Pasivo**: esta es la configuración predeterminada si no ha habilitado el rastreo de X-Ray en una etapa de API. Este enfoque significa que la API de API Gateway solo se rastrea si X-Ray se ha activado en un servicio ascendente.
+ **Activo**: cuando una etapa de API de API Gateway tiene esta configuración, API Gateway muestrea automáticamente las solicitudes de invocación de API, basándose en el algoritmo de muestreo especificado por X-Ray.
Cuando el rastreo activo está habilitado en una etapa, API Gateway crea un rol vinculado al servicio en su cuenta, si el rol aún no existe. El rol se denomina `AWSServiceRoleForAPIGateway` y llevará asociada la política administrada `APIGatewayServiceRolePolicy`. Para obtener más información acerca de los roles vinculados a servicio, consulte [Uso de roles vinculados a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
**nota**
X-Ray aplica un algoritmo de muestreo para garantizar que el rastreo sea eficiente, al tiempo que proporciona una muestra representativa de las solicitudes que recibe la API. El algoritmo de muestreo predeterminado es de una solicitud por segundo, con un muestreo del 5 por ciento de las solicitudes una vez pasado ese límite.
Puede cambiar el modo de rastreo de la API a través de la consola de administración de API Gateway, la CLI de API Gateway o un AWS SDK.
## Permisos para el rastreo de X-Ray
Al habilitar el rastreo de X-Ray en una etapa, API Gateway crea un rol vinculado al servicio en su cuenta, si el rol aún no existe. El rol se denomina `AWSServiceRoleForAPIGateway` y llevará asociada la política administrada `APIGatewayServiceRolePolicy`. Para obtener más información acerca de los roles vinculados a servicio, consulte [Uso de roles vinculados a servicios](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
## Activación del rastreo de X-Ray en la consola de API Gateway
Puede utilizar la consola de Amazon API Gateway para habilitar el rastreo activo en una etapa de API.
En estos pasos se presupone que ya ha implementado la API en una etapa.
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija la API y, a continuación, en el panel de navegación principal, elija **Etapas**.
1. En el panel **Etapas**, elija una etapa.
1. En la sección **Registros y rastreo**, elija **Editar**.
1. Para habilitar el rastreo activo de X-Ray, seleccione **Habilitar rastreo de X-Ray** para activarlo.
1. Seleccione **Save changes (Guardar cambios)**.
Una vez que haya habilitado X-Ray en la etapa de la API, puede utilizar la consola de administración de X-Ray para ver los rastros y los mapas de servicio.
## Habilitación del rastreo de AWS X-Ray mediante la CLI de API Gateway
El siguiente comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) permite crear una etapa con rastreo activo de X-Ray:
```
aws apigateway create-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--deployment-id deployment-id \
--region region \
--tracing-enabled=true
```
El resultado será similar al siguiente:
```
{
"tracingEnabled": true,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533849811,
"createdDate": 1533849811,
"methodSettings": {}
}
```
El siguiente comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) permite crear una etapa sin rastreo activo de X-Ray:
```
aws apigateway create-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--deployment-id deployment-id \
--region region \
--tracing-enabled=false
```
El resultado será similar al siguiente:
```
{
"tracingEnabled": false,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533849811,
"createdDate": 1533849811,
"methodSettings": {}
}
```
El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) permite activar el rastreo activo de X-Ray para una API implementada:
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--patch-operations op=replace,path=/tracingEnabled,value=true
```
El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) permite desactivar el rastreo activo de X-Ray para una API implementada:
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name stage-name \
--region region \
--patch-operations op=replace,path=/tracingEnabled,value=false
```
El resultado será similar al siguiente:
```
{
"tracingEnabled": false,
"stageName": stage-name,
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": deployment-id,
"lastUpdatedDate": 1533850033,
"createdDate": 1533849811,
"methodSettings": {}
}
```
Una vez que haya habilitado X-Ray para la etapa de su API, utilice la CLI de X-Ray para obtener información de rastreo. Para obtener más información, consulte [Uso de la API de X-Ray con la AWS CLI](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial).