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 WebSocket do API Gateway, ative o log de execução e o log de acesso usando o Amazon CloudWatch Logs.

Observação: atualmente, as APIs HTTP oferecem suporte somente ao log de acesso, e a configuração do 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:

• As solicitações que sua API recebe
• As respostas do 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

Crie um perfil do IAM para fazer login no CloudWatch

1.    No console do AWS Identity and Access Management (IAM), no painel de navegação, selecione Funções.

2.    No painel Funções, selecione Criar função.

3.    Na página Criar função, faça o seguinte:
Para o tipo de Entidade confiável, selecione AWS Service.
Para o caso de uso, selecione API Gateway.
Selecione o botão de rádio do API Gateway.
Selecione Próximo.

4.    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.

5.    Selecione Próximo.

6.    Em Nomeie, revise e crie, faça o seguinte:
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) Adicione etiquetas.
Selecione Criar função.

7.    No painel Funções, na barra de pesquisa, digite o nome da função que você criou. Em seguida, selecione a função nos resultados da pesquisa.

8.    No painel Resumo, copie o ARN da função. Você precisará desse Nome do recurso da Amazon (ARN) na próxima seção.

Para obter mais informações, consulte Permissões para criação de logs do CloudWatch.

Adicione o perfil do IAM no console do API Gateway

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

1.    No console do API Gateway, no painel APIs, selecione o nome de uma API que você criou. Essa é uma API REST ou uma API WebSocket (não uma API HTTP).

2.    No painel de navegação esquerdo, na parte inferior, abaixo da seção Certificados de cliente, selecione Configurações.

3.    Em Configurações, para o ARN da função de log do CloudWatch, cole o ARN do perfil do IAM que você copiou.

4.    Selecione Salvar.
Observação: o console não confirma que o ARN foi salvo.

Ative o log em sua API e faça o estágio

1.    No console do API Gateway, no painel APIs, selecione o nome de uma API que você criou.

2.    No painel de navegação esquerdo, selecione Estágio. Em seguida, selecione o nome artístico desejado.

3.    Selecione a guia Logs/Rastreamento.

4.    Na guia Logs/Rastreamento, em Configurações do CloudWatch, faça o seguinte para ativar o log de execução:
Marque a caixa de seleção Ativar o CloudWatch Logs.
Em Nível de log, selecione INFO para gerar logs de execução para todas as solicitações. Ou selecione ERROR para gerar logs de execução somente para solicitações à sua API que resultam em um erro.
Para APIs REST, marque a caixa de seleção Criar logs de dados completos de solicitações/respostas. Ou, para APIs WebSocket, marque a caixa de seleção Criar log de dados completos da mensagem.

5.    Em Log de acesso personalizado, faça o seguinte para ativar o log de acesso:
Marque a caixa de seleção Ativar log de acesso.
Para o ARN de destino do log de acesso, insira o ARN de um Amazon Kinesis Data Firehose (isso só é compatível com APIs REST) ou um grupo de logs do CloudWatch.

Insira um formato de log. Para obter orientação, selecione CLF, JSON, XML ou CSV para ver um exemplo nesse formato.

6.    Selecione Salvar alterações.
Observação: o console não confirma que as configurações foram salvas.

Para obter mais informações, consulte Configurar o log da API do CloudWatch usando o console do API Gateway.

Testar sua configuração de log

1.    Envie uma nova solicitação para sua API usando seu aplicativo cliente ou uma ferramenta como o aplicativo Postman ou o wscat (para APIs de WebSocket).

2.    No console do CloudWatch, no painel de navegação esquerdo, em Logs, selecione grupo de logs.

3.    Na lista de grupos de logs, selecione o grupo de logs da API que você está depurando.
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 de fluxos de log, escolha o fluxo de logs com a última hora do último evento. Essa seleção permitirá que você veja 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