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

O comando create-stage 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 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 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 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.