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 com APIs REST do API Gateway.

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.

  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.

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. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Escolha a API e, no painel de navegação principal, selecione Estágios.

3. No painel Estágios, selecione um estágio.

4. Na seção Logs e rastreamento, selecione Editar.

5. Para habilitar o rastreamento ativo com X-Ray, selecione Habilitar rastreamento com X-Ray para ativar o rastreamento com X-Ray.

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

Para usar a AWS CLI a fim de habilitar o rastreamento ativo do X-Ray para um estágio da API ao criar o estágio, chame o comando create-stage conforme o seguinte exemplo:

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

Veja a seguir um exemplo de saída para uma invocação bem-sucedida:

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

Para usar a AWS CLI a fim de desabilitar o rastreamento ativo do X-Ray para um estágio da API ao criar o estágio, chame o comando create-stage conforme o seguinte exemplo:

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

Veja a seguir um exemplo de saída para uma invocação bem-sucedida:

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

Para usar a AWS CLI a fim de habilitar o rastreamento ativo do X-Ray para uma API que já foi implantada, chame o comando update-stage da seguinte forma:

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

Para usar a AWS CLI a fim de desabilitar o rastreamento ativo do X-Ray para uma API que já foi implantada, chame o comando update-stage conforme o seguinte exemplo:

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

Veja a seguir um exemplo de saída para uma invocação bem-sucedida:

{
    "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.