Configurar o registro em log do CloudWatch para uma API REST no API Gateway - Amazon API Gateway
Formatos de log do CloudWatch para o API GatewayPermissões para registro em log do CloudWatchConfigurar o registro em log da API do CloudWatch usando o console do API GatewayConfigurar o registro da API do CloudWatch usando o AWS CloudFormation

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configurar o registro em log do CloudWatch para uma API 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 logs incluem erros ou rastreamentos de execução (como cargas 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 assim por diante.

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 (expressas em um formato de sua escolha) e selecione um grupo de logs como o destino. 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. O $context.requestId registrará o valor no cabeçalho x-amzn-RequestId. Os clientes podem substituir o valor no cabeçalho x-amzn-RequestId por um valor no formato de um identificador universal exclusivo (UUID). O API Gateway retorna esse ID de solicitação no cabeçalho de resposta x-amzn-RequestId. O API Gateway substitui os IDs de solicitação sobrescritos que não estão no formato de um UUID por UUID_REPLACED_INVALID_REQUEST_ID nos logs de acesso. $context.extendedRequestId é um ID exclusivo que o API Gateway gera. O API Gateway retorna esse ID de solicitação no cabeçalho de resposta x-amz-apigw-id. Um autor da chamada de API não pode fornecer ou substituir esse ID de solicitação. Para obter mais informações, consulte $contextVariáveis para modelos de dados, autorizadores, modelos de mapeamento e registro de CloudWatch acesso.

nota

Somente as variáveis $context são compatíveis (não $input, etc.).

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, desde que a coluna ARN esteja selecionada para exibição. 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.

  • CLF (Formato de log comum):

    $context.identity.sourceIp $context.identity.caller  \
$context.identity.user [$context.requestTime] \
"$context.httpMethod $context.resourcePath $context.protocol" \
$context.status $context.responseLength $context.requestId $context.extendedRequestId

    Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

  • JSON: 

    { "requestId":"$context.requestId", \
  "extendedRequestId":"$context.extendedRequestId", \
  "ip": "$context.identity.sourceIp", \
  "caller":"$context.identity.caller", \
  "user":"$context.identity.user", \
  "requestTime":"$context.requestTime", \
  "httpMethod":"$context.httpMethod", \
  "resourcePath":"$context.resourcePath", \
  "status":"$context.status", \
  "protocol":"$context.protocol", \
  "responseLength":"$context.responseLength" \
}

    Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

  • XML: 

    <request id="$context.requestId"> \
    <extendedRequestId>$context.extendedRequestId</extendedRequestId>
    <ip>$context.identity.sourceIp</ip> \
    <caller>$context.identity.caller</caller> \
    <user>$context.identity.user</user> \
    <requestTime>$context.requestTime</requestTime> \
    <httpMethod>$context.httpMethod</httpMethod> \
    <resourcePath>$context.resourcePath</resourcePath> \
    <status>$context.status</status> \
    <protocol>$context.protocol</protocol> \
    <responseLength>$context.responseLength</responseLength> \
</request>

    Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

  • CSV (valores separados por vírgula):

    $context.identity.sourceIp,$context.identity.caller,\
$context.identity.user,$context.requestTime,$context.httpMethod,\
$context.resourcePath,$context.protocol,$context.status,\
$context.responseLength,$context.requestId,$context.extendedRequestId

    Os caracteres de continuação (\) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (\n) no final do formato de log para incluir uma nova linha no final de cada entrada de log.

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": "*"
        }
    ]
}
nota

O API Gateway chama o AWS Security Token Service para assumir a função do IAM. Portanto, certifique-se de que o AWS STS esteja habilitado para a região. Para obter mais informações, consulte Gerenciar o AWS STS em uma região da AWS.

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.

  1. Inicie uma sessão 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 de função 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, selecione APIs e siga um destes procedimentos:

    1. Selecione uma API e escolha um estágio.

    2. Crie uma API e implante-a em um estágio.

  5. No painel de navegação principal, selecione Estágios.

  6. Na seção Logs e rastreamento, selecione Editar.

  7. Para habilitar o registro de execução em logs:

    1. Selecione um nível de registro em log no menu suspenso CloudWatch Logs.

      Atenção

      Logs completos de solicitações e respostas podem ser úteis para solucionar problemas de APIs, mas podem ocasionar o registro em log de dados sigilosos. Recomendamos que você não use Logs completos de solicitações e respostas para APIs de produção.

    2. Se desejar, selecione Métricas detalhadas para ativar as métricas detalhadas do CloudWatch.

    Para obter mais informações sobre métricas do CloudWatch, consulte Monitorar a execução da API REST com métricas do Amazon CloudWatch.

  8. Para habilitar o registro de acesso em logs:

    1. Ative o Registro em log de acesso personalizado.

    2. Em Acessar ARN de destino do log, insira o ARN de um grupo de logs. O formato do ARN é arn:aws:logs:{region}:{account-id}:log-group:log-group-name.

    3. Em Formato do log, insira um formato de log. É possível escolher CLF, JSON, XML ou CSV. Para saber mais sobre exemplos de formatos de log, consulte Formatos de log do CloudWatch para o API Gateway.

  9. Escolha Save changes (Salvar alterações).

nota

Você pode permitir o registro em log de execução e o de acesso independentemente um do outro.

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