Configuración de AWS X-Ray con las API REST de API Gateway

En esta sección, encontrará información detallada acerca de cómo configurar AWS X-Ray con las API REST de API Gateway.

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. Este rol se llama AWSServiceRoleForAPIGateway y tendrá la política administrada APIGatewayServiceRolePolicy asociada. Para obtener más información acerca de los roles vinculados a servicio, consulte Uso de roles vinculados a servicios.

  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. Este rol se llama AWSServiceRoleForAPIGateway y tendrá la política administrada APIGatewayServiceRolePolicy asociada. Para obtener más información acerca de los roles vinculados a servicio, consulte Uso de roles vinculados a servicios.

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.

2. Elija la API y, a continuación, en el panel de navegación principal, elija Etapas.

3. En el panel Etapas, elija una etapa.

4. En la sección Registros y rastreo, elija Editar.

5. Para habilitar el rastreo activo de X-Ray, seleccione Habilitar rastreo de X-Ray para activarlo.

6. Elija 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

Si desea utilizar la AWS CLI para habilitar el rastreo activo de X-Ray en una etapa de la API al momento de crear la etapa, llame al comando create-stage, como se muestra en el siguiente ejemplo:

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

A continuación, se muestra un ejemplo del resultado de una invocación realizada correctamente:

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

Si desea utilizar la AWS CLI para desactivar el rastreo activo de X-Ray en una etapa de la API al momento de crear la etapa, llame al comando create-stage, como se muestra en el siguiente ejemplo:

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

A continuación, se muestra un ejemplo del resultado de una invocación realizada correctamente:

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

Si desea utilizar la AWS CLI para habilitar el rastreo activo de X-Ray en una API que ya se ha implementado, llame al comando update-stage, tal como se indica a continuación:

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

Si desea utilizar la AWS CLI para desactivar el rastreo activo de X-Ray en una API que ya se ha implementado, llame al comando update-stage, tal como se muestra en el siguiente ejemplo:

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 continuación, se muestra un ejemplo del resultado de una invocación realizada correctamente:

{
    "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 AWS X-Ray con la AWS CLI.