View a markdown version of this page

Registro em log de execução para APIs REST - Amazon API Gateway
Registro em log de execução padrãoEntrega do Amazon CloudWatch Logs para logs de execução

Registro em log de execução para APIs REST

O registro em log de execução registra as ações que o API Gateway realiza para processar uma solicitação de API. Os dados registrados em log incluem erros, rastreamentos de execução, cargas úteis ou valores de parâmetros de solicitação e de resposta, dados usados por autorizadores do Lambda, além de informações que indicam se as chaves de API são obrigatórias e se os planos de uso estão habilitados. O API Gateway edita cabeçalhos de autorização, valores de chave de API e parâmetros de solicitação confidenciais semelhantes dos dados registrados em log.

Para melhorar seu procedimento de segurança, recomendamos que você use o registro em log de execução no nível ERROR ou INFO. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte Amazon API Gateway controls no Guia do usuário do AWS Security Hub.

Registro em log de execução padrão

Quando você habilita o registro em log de execução em um estágio, o API Gateway cria e gerencia automaticamente um grupo de logs do CloudWatch Logs. O nome do grupo de logs é API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}. Dentro de cada grupo de logs, os logs são divididos em fluxos de logs ordenados por Hora do último evento.

Com o registro em log de execução padrão:

  • Os eventos de logs são truncados em 1 KB.

  • O API Gateway gerencia o nome do grupo de logs. Não é possível escolher o nome do grupo de logs nem enviar logs diretamente para o Amazon S3 ou o Firehose.

Para habilitar o registro em log de execução padrão, defina loggingLevel em seu estágio como ERROR ou INFO. Nenhuma outra configuração é necessária.

Permissões

Para habilitar o CloudWatch Logs, é necessário conceder permissão ao API Gateway para ler e gravar logs no CloudWatch para sua conta. A política gerenciada AmazonAPIGatewayPushToCloudWatchLogs tem todas as permissões necessárias.

Crie um perfil do IAM com apigateway.amazonaws.com como entidade confiável, anexe a política anterior e defina o ARN do perfil do IAM na propriedade cloudWatchRoleArn em sua Conta. É necessário definir essa propriedade separadamente para cada região da AWS na qual você deseja habilitar o CloudWatch Logs.

nota

O API Gateway chama o AWS Security Token Service para assumir o perfil do IAM, portanto, o AWS STS deve estar habilitado para a região. Para obter mais informações, consulte Gerenciar o AWS STS em uma região da AWS.

Habilitar o registro em log de execução (console)

Antes de começar, implante a API em um estágio e configure um ARN de perfil do CloudWatch Logs apropriado para sua conta.

  1. Faça login no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. No painel de navegação principal, selecione Configurações e, em Registro em log, selecione Editar.

  3. Em ARN do perfil do log do CloudWatch, insira o ARN de um perfil do IAM com as permissões apropriadas. É necessário fazer isso uma vez para cada Conta da AWS que cria APIs usando o API Gateway.

  4. No painel de navegação principal, escolha APIs, selecione sua API REST e, em seguida, escolha Estágios.

  5. Escolha um estágio e, na seção Logs e rastreamento, selecione Editar.

  6. Escolha um nível de registro em log no menu suspenso CloudWatch Logs:

    • Desativado: o API Gateway não registra as solicitações para esse estágio.

    • Somente erros: o API Gateway registra somente os erros.

    • Logs de erros e informações: o API Gateway registra todos os eventos.

  7. (Opcional) Selecione Rastreamento de dados para registrar dados completos de solicitação e resposta. Isso pode resultar no registro em log de dados sensíveis.

    nota

    Recomendamos não usar Rastreamento de dados para APIs de produção.

  8. (Opcional) Selecione Métricas detalhadas para ativar as métricas detalhadas do CloudWatch. Para obter mais informações, consulte Monitorar a execução da API REST com métricas do Amazon CloudWatch.

  9. Escolha Salvar alterações.

Não é necessário reimplantar a API ao atualizar as configurações do estágio.

Habilitar o registro em log de execução (CloudFormation)

Use a propriedade MethodSettings no recurso de estágio para habilitar o registro em log de execução.

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO

Para habilitar o CloudWatch Logs, é necessário conceder permissão ao API Gateway para ler e gravar logs no CloudWatch para sua conta. Para saber mais, consulte Associar a conta ao perfil do IAM no Guia do usuário do AWS CloudFormation.

Entrega do Amazon CloudWatch Logs para logs de execução

A entrega do Amazon CloudWatch Logs oferece um caminho alternativo para logs de execução. Em vez de gravar em um grupo de logs gerenciado pelo API Gateway, configure uma entrega que envia logs de execução para destinos que você possui e controla.

Com a entrega do Amazon CloudWatch Logs:

  • Os eventos de log podem ter até 1 MB, capturando dados de solicitação e resposta mais completos. As cargas úteis que excedem 1 MB ainda são truncadas.

  • Você escolhe o destino: seus próprios grupos de logs do CloudWatch Logs, buckets do Amazon S3 ou fluxos do Firehose.

  • É possível enviar logs para vários destinos simultaneamente.

  • Você controla a configuração do grupo de logs, incluindo a nomenclatura e a retenção.

Importante

A entrega do CloudWatch Logs substitui o registro em log de execução padrão. Quando você configura uma entrega, o API Gateway para de gravar no grupo de logs gerenciado automaticamente. Não é possível usar os dois caminhos ao mesmo tempo para o mesmo estágio.

Quando você cria uma entrega, o API Gateway roteia os logs de execução para os destinos configurados, em vez de enviá-los ao grupo de logs gerenciado automaticamente. Quando você exclui uma entrega, os logs de execução retomam automaticamente o fluxo para o grupo de logs gerenciado automaticamente. Nenhuma alteração de configuração no API Gateway é necessária, além do pré-requisito de definir loggingLevel como ERROR ou INFO.

nota

A entrega de logs é feita com base no melhor esforço. Em casos raros, alguns eventos de log podem não ser entregues.

Atenção

Antes de habilitar a entrega de logs, atualize todos os painéis, alarmes ou filtros de assinatura que façam referência ao grupo de logs gerenciado automaticamente (API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}). Depois que a entrega estiver ativa, esse grupo de logs não receberá mais novos eventos.

A tabela a seguir compara o registro em log de execução padrão com a entrega do Amazon CloudWatch Logs.

Registro em log de execução padrão Entrega do Amazon CloudWatch Logs
Tamanho máximo do evento de logs 1 KB 1 MB
Destinos CloudWatch Logs (grupo de logs gerenciado) CloudWatch Logs, Amazon S3, Firehose (seus próprios recursos)
Vários destinos Não Sim
Nome do grupo de logs Definido pelo API Gateway Você escolhe
Configuração Automática quando o registro em log está habilitado Requer a criação de uma entrega do Amazon CloudWatch Logs
Pré-requisito Definir loggingLevel como ERROR ou INFO Definir loggingLevel como ERROR ou INFO
nota

Se você definir loggingLevel como OFF depois de configurar uma entrega, nenhum log de execução será gerado ou entregue. Seus destinos de entrega permanecerão configurados, mas não receberão dados.

Para criar uma entrega, consulte Criar uma entrega para logs de execução da API REST.