Como posso usar os logs do 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 em log 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 AWS Identity and Access Management (AWS IAM) do API Gateway. Para obter instruções, consulte Como faço para ativar o CloudWatch Logs para solucionar problemas com minha API REST do API Gateway ou API de WebSocket?

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

Resolução

Depois de ativar o registro em 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 continuar a solucionar seus problemas. Para obter mais informações, consulte Formatos de log do CloudWatch para o 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 Por que estou recebendo erros 401 Não autorizado 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 em log, 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, analise 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 Como posso solucionar erros “429 Muitas solicitações” ou “Limite excedido” 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, analise os seguintes tipos de log para obter mais informações.

Observação: para logs de solicitações, você deve selecionar Logs de erros e informações no menu suspenso dos 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 em log, 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ção de endpoint

Os logs de solicitação de endpoint 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 logs a 1.024 bytes. O API Gateway trunca eventos de logs maiores que 1.024 bytes, como corpos de solicitação e resposta, antes que os logs sejam enviados aos CloudWatch Logs.

Informações relacionadas

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

Configurar o registro em log do CloudWatch para APIs REST no API Gateway

Monitorar a execução da API REST com métricas do Amazon CloudWatch

Monitorar a execução de APIs de WebSocket com métricas do CloudWatch

Troubleshooting Amazon API Gateway with enhanced observability variables (Solução de problemas do Amazon API Gateway com variáveis de observabilidade aprimoradas)