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

Para ajudar a depurar problemas relacionados à execução de solicitação ou ao acesso do cliente à sua API, é possível permitir que o Amazon CloudWatch Logs registre chamadas de API em log. Para obter mais informações sobre o CloudWatch, consulte Monitorar a execução da API REST com métricas do Amazon CloudWatch.

Formatos de log do CloudWatch para o API Gateway

Há dois tipos de registro de API em logs no CloudWatch: registro de execução e de acesso. No registro de execução, o API Gateway gerencia o CloudWatch Logs. O processo inclui a criação de grupos de log e fluxos de log, além de relatórios aos fluxos de log sobre solicitações e respostas de qualquer autor da chamada.

Os dados registrados em log incluem erros ou rastreamentos de execução (como cargas úteis ou valores de parâmetro de solicitação ou de resposta), dados usados por autorizadores do Lambda (anteriormente conhecidos como autorizadores personalizados), independentemente de as chaves de API serem necessárias ou de os planos de uso estarem ativos e outras informações. 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.

Quando você implanta uma API, o API Gateway cria um grupo de logs e registra os streams no grupo de logs. O grupo de logs é chamado seguindo o formato API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}. Dentro de cada grupo de logs, os logs são subdivididos em fluxos de log, os quais são ordenados por Last Event Time conforme os dados registrados em log são reportados.

No registro de acessos, você, assim como um desenvolvedor de API, registra quem acessou sua API e como o autor da chamada acessou a API. Você pode criar seu próprio grupo de logs ou escolher um existente que possa ser gerenciado pelo API Gateway. Para especificar os detalhes de acesso, selecione variáveis $context, um formato de log e um destino do grupo de logs.

O formato do log de acesso deve incluir ao menos $context.requestId ou $context.extendedRequestId. Como prática recomendada, inclua $context.requestId e $context.extendedRequestId em seu formato de log.

Escolha um formato de log que também seja adotado pelo seu backend de análise, como Common Log Format (CLF), JSON, XML ou CSV. Em seguida, você pode enviar os logs de acesso a ele diretamente para que suas métricas sejam calculadas e produzidas. Para definir o formato de log, defina o ARN do grupo de logs na propriedade accessLogSettings/destinationArn no estágio. Você pode obter o ARN de um grupo de logs no console do CloudWatch. Para definir o formato de log de acesso, defina um formato escolhido na propriedade accessLogSetting/format no estágio.

Exemplos de alguns formatos de log de acesso comumente usados são mostrados no console do API Gateway e estão listados a seguir.

Permissões para registro em log do CloudWatch

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 (com um Nome de região da Amazon (ARN) de arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) tem todas as permissões necessárias:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

Para conceder essas permissões à sua conta, crie uma função do IAM com apigateway.amazonaws.com como entidade confiável, anexe a política anterior à função do IAM e defina o ARN da função do IAM na propriedade cloudWatchRoleArn em sua conta. Você deve definir a propriedade CloudWatchroLearn separadamente para cada região da AWS na qual deseja habilitar o CloudWatch Logs.

Se você receber um erro ao definir o ARN da função do IAM, verifique as configurações da sua conta da AWS Security Token Service para garantir que o AWS STS esteja habilitado na região que você está usando. Para obter mais informações sobre como ativar o AWS STS, consulte Gerenciar o AWS STS em uma região da AWS no Guia do usuário do IAM.

Configurar o registro em log da API do CloudWatch usando o console do API Gateway

Para configurar o registro em log da API do CloudWatch, é necessário ter implantado a API em um estágio. Você também deve ter configurado um ARN de função do CloudWatch Logs adequado para a sua conta.

O API Gateway já está pronto para registrar solicitações à sua API em log. Não é necessário reimplantar a API ao atualizar as configurações do estágio, os logs ou as variáveis do estágio.

Configurar o registro da API do CloudWatch usando o AWS CloudFormation

Use o modelo do AWS CloudFormation de exemplo a seguir para criar um grupo de logs do Amazon CloudWatch Logs e configurar a execução e o registro de acesso para um estágio. 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.

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      Description: "test stage description"
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO
      AccessLogSetting:
        DestinationArn: !GetAtt MyLogGroup.Arn
        Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId
  MyLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Join
        - '-'
        - - !Ref MyAPI
          - access-logs