Como encontro erros da API REST do API Gateway em meus logs do CloudWatch?

Resolução

O CloudWatch fornece dois tipos de registro em log de API: registro em log de acesso e de execução. Para obter mais informações sobre os diferentes tipos de registro em log de API, consulte Formatos de log do CloudWatch para o API Gateway.

Para encontrar uma falha específica na solicitação da API REST do API Gateway usando os logs do CloudWatch, faça o seguinte.

Observação: se você receber erros ao executar comandos da AWS Command Line Interface (AWS CLI), verifique se está usando a versão mais recente da AWS CLI.

Para encontrar uma falha na solicitação da API REST usando os logs de acesso do CloudWatch

1.    Configure o log de acesso do API CloudWatch usando o console do API Gateway.

Observação: o exemplo a seguir usa o formato de log JSON CloudWatch e inclui um campo de mensagem para o contexto $context.error.message.

2.    Execute o comando filter-log-events da AWS CLI nos logs de acesso do API Gateway usando seu utilitário de pesquisa preferido.

Exemplo de comando filter-log-events que usa o utilitário de pesquisa “grep” para logs de acesso ao API Gateway

Importante: altere o log-group-name para o nome do grupo de logs de acesso.

aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep '17cb49b2-c061-11e9-bc30-f118c8b08d5f'

3.    Verifique a resposta ao comando filter-log-events para identificar erros. A resposta do comando retornará um objeto com todas as variáveis $context que você mapeou.

Exemplo de resposta do comando filter-log-events

{
    "requestId": "17cb49b2-c061-11e9-bc30-f118c8b08d5f",
    "ip": "1.2.3.4",
    "caller": "-",
    "user": "-",
    "requestTime": "28/Aug/2019:15:10:34 +0000",
    "httpMethod": "GET",
    "resourcePath": "/iam",
    "status": "403",
    "message": "Missing Authentication
            Token",
    "protocol": "HTTP/1.1",
    "responseLength": "42"
}

Para encontrar uma falha na solicitação da API REST usando os logs de execução do CloudWatch

1.    Configure o log de execução do API CloudWatch usando o console do API Gateway.

Importante: para evitar o armazenamento de informações confidenciais, desative a opção Registrar em log dados completos de solicitações/respostas antes de passar para a produção.

2.    Execute o seguinte comando cURL para replicar a solicitação de API que falhou:

Importante: substitua abcd1234 pelo seu ID de API e us-east-1 pela região da AWS em que sua API está.

curl -X GET https://abcd1234.execute-api.us-east-1.amazonaws.com/dev/myapi -v

3.    Observe o valor x-amzn-requestid nos cabeçalhos de resposta da API. Esse valor é necessário na próxima etapa.

Exemplo de cabeçalhos de resposta do API Gateway

< content-type: application/json
< content-length: 41
< x-amzn-requestid: 17cb49b2-c061-11e9-bc30-f118c8b08d5f
< x-amz-apigw-id: eh7enHGIvHcFnPg=

4.    Execute o comando filter-log-events da AWS CLI nos logs de execução do API Gateway usando seu utilitário de pesquisa preferido.

Exemplo de comando filter-log-events que usa o utilitário de pesquisa “grep” para logs de execução do API Gateway

Importante: altere o log-group-name para o nome do grupo de logs de acesso.

aws logs filter-log-events --log-group-name 'API-Gateway-Execution-Logs_2mg2xeej0a/test' | grep '17cb49b2-c061-11e9-bc30-f118c8b08d5f'

5.    Verifique a resposta ao comando filter-log-events para identificar erros. Veja a seguir exemplos dos tipos de mensagens de erro que você pode ver:

Exemplos de erros de permissões do API Gateway

(b59c91c8-3386-4478-b2b4-c4d63191756e) Execution failed due to configuration error: Invalid permissions on Lambda function
(b59c91c8-3386-4478-b2b4-c4d63191756e) Gateway response type: DEFAULT_5XX with status code: 500
(b59c91c8-3386-4478-b2b4-c4d63191756e) Gateway response body: {"message": "Internal server error"}

Exemplo de erros de tempo limite de integração do API Gateway

(2a1db04d-ac7c-463f-b9bd-478285467d58) Execution failed due to a timeout error
(2a1db04d-ac7c-463f-b9bd-478285467d58) Gateway response type: DEFAULT_5XX with status code: 504
(2a1db04d-ac7c-463f-b9bd-478285467d58) Gateway response body: {"message": "Endpoint request timed out"}

Exemplo de erros de integração de back-end do API Gateway

(631ff793-2c5b-413d-a31d-f2cd3f75708b) Endpoint response body before transformations: {"errorMessage": "division by zero", "errorType": "ZeroDivisionError", "stackTrace": [" File \"/var/task/lambda_function.py\", line 7, in lambda_handler\n c=a/b\n"]}
(631ff793-2c5b-413d-a31d-f2cd3f75708b) Lambda execution failed with status 200 due to customer function error: division by zero. Lambda request id: 7f0d8fc1-33ce-4bf9-8685-df78e179da5c
(631ff793-2c5b-413d-a31d-f2cd3f75708b) Gateway response type: DEFAULT_5XX with status code: 502
(631ff793-2c5b-413d-a31d-f2cd3f75708b) Gateway response body: {"message": "Internal server error"}

Se você não conseguir obter o ID da solicitação

1.    Obtenha o código de status HTTP ou a mensagem de erro retornada, ou ambos, dos logs do aplicativo do lado do cliente.

2.    Execute o comando filter-log-events da AWS CLI nos logs de acesso do API Gateway. Use o utilitário de pesquisa “grep” para o código de status HTTP ou para a mensagem de erro retornada.

Exemplo de comando filter-log-events que usa o utilitário de pesquisa “grep” para um código de status HTTP

aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep '504'

Exemplo de comando filter-log-events que usa o utilitário de pesquisa “grep” para uma mensagem de erro retornada do lado do cliente

aws logs filter-log-events --log-group-name 'API-Gateway-Access-Logs_2mg2xeej0a/test' | grep 'Endpoint request timed out'

3.    Encontre o ID da solicitação nos resultados dos logs de acesso.

4.    Siga o procedimento na seção Rastreamento de respostas de API em logs de execução deste artigo.

---