Como faço para ativar o CloudWatch Logs para solucionar problemas com minha API REST do API Gateway ou API WebSocket?

Breve descrição

Para solucionar problemas de uma API REST ou API de WebSocket do API Gateway, use Amazon CloudWatch Logs para ativar o log de execução e o log de acesso.

Observação: APIs HTTP atualmente oferecem apenas registro em log de acesso. A configuração do registro em log é diferente para essas APIs. Para obter mais informações, consulte Configurar logs para uma API HTTP.

Os logs de execução contêm informações que você pode usar para identificar e solucionar a maioria dos erros de API. Por exemplo, os logs podem conter as seguintes informações:

• Solicitações que sua API recebe
• Respostas de back-end de integração da sua API
• A resposta fornecida pelos autorizadores do AWS Lambda
• O requestId para endpoints de integração da AWS
• Informações sobre se uma chave de API fornecida foi autorizada

Os logs de acesso contêm detalhes sobre quem acessou sua API e como eles a acessaram. Você também pode usar os logs para solucionar erros de API. Para obter mais informações sobre cada tipo de log, consulte formatos de log do CloudWatch para API Gateway.

Resolução

Criar um perfil do IAM para fazer logon no CloudWatch

Para criar um perfil do AWS Identity and Access Management (IAM) para enviar logs ao CloudWatch, conclua as seguintes etapas:

1. Abra o console do IAM.
2. No painel de navegação, escolha Perfis.
3. No painel Perfis, selecione Criar perfil.
4. Na página Criar perfil, insira as seguintes informações:
   Em Entidade confiável, escolha Serviço da AWS.
   Para o caso de uso, selecione API Gateway.
   Selecione o botão de opção Gateway de API.
   Escolha Avançar.
5. Em Políticas de permissões, observe que a política gerenciada pela AWS AmazonAPIGatewayPushToCloudWatchLogs está selecionada por padrão. A política tem todas as permissões necessárias.
6. Escolha Avançar.
7. Em Nomear, revisar e criar, insira as seguintes informações:
   Em Nome da função, insira um nome para a função.
   (Opcional) Em Descrição da função, edite a descrição de acordo com suas preferências.
   (Opcional) Adicionar etiquetas.
   Selecione Criar perfil.
8. No painel Perfis, na barra de pesquisa, digite o nome da função que você criou. Em seguida, escolha o perfil.
9. No painel Resumo, copie o ARN da função. Você precisa desse ARN na próxima seção.

Para obter mais informações, consulte Permissões para registro em log do CloudWatch.

Adicione o perfil do IAM no console do API Gateway

Para adicionar a perfil do IAM ao console do API Gateway, conclua as seguintes etapas:

1. Abra o console do API Gateway.
2. No painel APIs, escolha o nome de uma API que você criou. Esta é uma API REST ou uma API de WebSocket e não uma API HTTP.
3. No painel de navegação, selecione Configurações.
4. Em Configurações, para ARN do perfil do log do CloudWatch, insira o ARN do perfil do IAM.
   Observação: o perfil de log do CloudWatch é uma configuração em nível de região da AWS e é usada com todas as APIs nessa região da AWS.
5. Escolha Salvar.

Observação: se você desenvolve várias APIs em diferentes regiões da AWS, conclua essas etapas em cada região da AWS.

Ativar o log na sua API e seu estágio

Para ativar a geração de logs para sua API e seu estágio, conclua as etapas a seguir:

1. Abra o console do API Gateway.
2. No painel de navegação, escolha APIs e selecione sua API.
3. No painel de navegação, escolha Estágios. Em seguida, selecione seu estágio.
4. Em Logs e rastreamento, escolha Editar.
5. Em Logs do CloudWatch, conclua as tarefas a seguir para ativar o log de execução:
   Na lista suspensa, escolha seu nível de log:
   Escolha Somente erros para gerar logs de execução somente para solicitações à sua API que resultem em erro.
   Escolha Log de erros e informações para gerar logs de execução para todas as solicitações.
   Escolha Solicitações completas e logs de resposta para gerar registros detalhados para todos os eventos.
   Observação: Solicitações completas e logs de resposta é útil para solução de problemas, mas pode registrar dados confidenciais. É uma prática recomendada não usar Solicitações completas e logs de resposta para APIs de produção.
6. Em Registro de logs de acesso personalizado, conclua as tarefas a seguir para ativar a criação de logs de acesso:
   Marque a caixa de seleção Habilitar registro de logs.
   Em ARN de destino de logs de acesso, insira o ARN de um Amazon Kinesis Data Firehose ou um Grupo de logs do CloudWatch.
   Observação: o ARN do Amazon Kinesis Data Firehose é compatível apenas com APIs REST.
7. Insira um formato de log.
8. Selecione Salvar alterações.

Para mais informações, consulte CloudWatch log formats for API Gateway.

Testar sua configuração de log

Para enviar uma nova solicitação à sua API, use sua aplicação cliente ou outra ferramenta, como o app Postman ou o wscat para APIs WebSocket.

Para testar sua configuração de registro em log, conclua as etapas a seguir:

1. Abra o console do CloudWatch.
2. No painel de navegação, em Logs, escolha Grupos de logs.
3. Na lista de Grupos de logs, escolha o grupo de logs da API que você deseja depurar.
   Para APIs REST, o nome do grupo de logs está no seguinte formato: API-Gateway-Execution-Logs_apiId/stageName.
   Para APIs de WebSocket, o nome do grupo de log está no seguinte formato: /aws/apigateway/apiId/stageName.
   Observação: os logs de acesso estão localizados no grupo de logs cujo ARN foi especificado quando você ativou o logs de acesso.
4. Na lista Fluxos de log, escolha o fluxo de logs com a Horário do último evento. Essa seleção permite ver mensagens com os detalhes de execução ou acesso da sua solicitação.

Para obter mais informações, consulte Exibir eventos de log do API Gateway no console do CloudWatch.

Informações relacionadas

Configurar o log do CloudWatch para uma API REST no API Gateway

Modelo de mapeamento do API Gateway e referência da variável de log de acesso

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

Monitoramento da execução da API WebSocket com métricas do CloudWatch