Como posso usar os logs do Amazon API Gateway para solucionar problemas de API?

Breve descrição

Para solucionar problemas de uma API REST ou API de WebSocket do API Gateway, ative o registro de execução e, em seguida, use o Amazon CloudWatch Logs para acessar seus logs. Certifique-se de anexar todas as permissões necessárias ao perfil do API Gateway AWS Identity and Access Management (AWS IAM). Para obter instruções, consulte How do I turn on CloudWatch Logs to troubleshoot my API Gateway REST API or WebSocket API? (Como eu ativo o CloudWatch Logs para solucionar problemas com minha API REST API Gateway ou API de WebSocket?)

Observação: as APIs HTTP suportam somente o registro de acesso. Para obter mais informações sobre como configurar o log para essas APIs, consulte Configurar o log para APIs HTTP no API Gateway.

Resolução

Depois de ativar o log, o API Gateway cria automaticamente um grupo de logs do CloudWatch chamado API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. Use esse grupo para solucionar ainda mais seus problemas. Para mais informações, consulte Formatos de log do CloudWatch para API Gateway.

Verifique se há erros de autorização

Se você ativar os AWS Lambda Authorizers para sua API, os logs indicarão se a solicitação foi autorizada e incluirão IDs do autorizador e da solicitação.

Exemplos de logs autorizados:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Exemplos de logs não autorizados:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

Para solucionar esse problema, consulte Why do I get API Gateway "401 Unauthorized" errors after I create a Lambda authorizer? (Por que recebo os erros “401 Unauthorized” do API Gateway depois de criar um autorizador do Lambda?)

Atualize a configuração do seu plano de uso

Depois que o autorizador do Lambda registra, o API Gateway verifica o plano de uso da solicitação de API. Se você não configurou um plano de uso, as solicitações de API não são contabilizadas nos limites do controle de utilização.

Exemplos de logs do plano de uso:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

Se você configurar APIs com chaves de API e o cabeçalho X-API-Key estiver ausente, os logs retornarão um erro semelhante à seguinte mensagem:

"API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present"

Para resolver esse problema, revise a configuração da API. Você deve associar a chave de API ao plano de uso necessário e incluir a chave na solicitação como cabeçalho X-API-KEY com o valor correto.

Se você adicionar a chave de API correta no cabeçalho e o API Gateway limitar a solicitação, os logs retornarão um erro semelhante à seguinte mensagem:

"API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429”

Para resolver esse problema, conclua as etapas em How can I troubleshoot "429 Too Many Requests" or "Limit Exceeded" errors for my API with API Gateway? (Como posso solucionar os erros de “429 Too Many Requests” ou “Limit Exceeded” em minha API com o API Gateway?)

Tipos de log de solicitações

Quando você ativa o rastreamento de dados e os logs de erros e informações, os logs do API Gateway contêm mais detalhes para ajudar você a solucionar problemas. Para descobrir onde a solicitação do API Gateway falha, revise os seguintes tipos de log para obter mais informações.

Observação: para logs de solicitações, você deve escolher Erros e logs de informações no menu suspenso de CloudWatch Logs. Em seguida, ative o rastreamento de dados para os logs de execução. Como o rastreamento de dados pode registrar dados sensíveis, não é uma prática recomendada ativar o Rastreamento de dados para APIs de produção.

Logs de solicitação de método

Os logs de solicitação de método incluem informações detalhadas que uma solicitação de API recebe, incluindo o caminho da solicitação, o parâmetro da consulta, o cabeçalho da solicitação e o corpo da solicitação.

Exemplo de log de solicitação de método:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

Logs de solicitações de endpoints

Os logs de solicitações de endpoints incluem informações detalhadas que uma solicitação de API recebe, incluindo o URI, os cabeçalhos da solicitação e o corpo da solicitação.

Exemplo de log de solicitação de endpoint:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

Os dados incluídos nas solicitações de endpoint são enviados para sua integração de backend para processamento adicional.

Logs de resposta do endpoint

Os logs de resposta do endpoint incluem os dados que as integrações de backend retornam, incluindo o código de status, cabeçalhos, corpo e latência de integração.

Exemplo de log de resposta do endpoint:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

Logs de resposta do método

Os logs de resposta do método incluem os cabeçalhos e o corpo enviados ao cliente após a transformação.

Exemplo de log de resposta do método:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

Importante: o API Gateway limita os eventos de log a 1024 bytes. O API Gateway trunca eventos de log maiores que 1024 bytes, como corpos de solicitação e resposta, antes que os logs sejam enviados aos CloudWatch Logs.

Informações relacionadas

Como solucionar problemas de CloudWatch Logs ausentes para APIs REST do API Gateway?

Configure o log do CloudWatch para APIs REST no API Gateway

Monitoramento da execução da API REST com Amazon CloudWatch Metrics

Monitorar a execução da API de WebSocket com CloudWatch Metrics

Solução de problemas do Amazon API Gateway com variáveis de observabilidade aprimoradas