View a markdown version of this page

Registro em log de acesso para APIs REST - Amazon API Gateway
Formatos de log de acessoConfigurar o registro em log de acesso usando o console do API GatewayConfigurar o registro em log de acesso usando o CloudFormation

Registro em log de acesso para APIs REST

No registro em log de acesso, você registra quem acessou sua API e como o autor da chamada acessou a API. É possível criar seu próprio grupo de logs ou escolher um grupo de logs existente. Para especificar os detalhes de acesso, selecione variáveis $context, um formato de log e um destino do grupo de logs.

Formatos de log de acesso

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

$context.requestId

Isso registra em log 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 substituídos que não estão no formato de um UUID com UUID_REPLACED_INVALID_REQUEST_ID nos logs de acesso.

$context.extendedRequestId

extendedRequestID é um ID exclusivo gerado pelo API Gateway. 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. Pode ser necessário fornecer esse valor ao suporte da AWS para ajudar a solucionar problemas de sua API. Para obter mais informações, consulte Variáveis para registro em log de acesso no API Gateway.

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.

  • 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

  • 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" }

  • 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>

  • 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

Configurar o registro em log de acesso usando o console do API Gateway

Antes de configurar o registro em log de acesso, 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 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.

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

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

  5. Ative o Registro em log de acesso personalizado.

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

  7. 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 de acesso.

  8. Escolha Salvar alterações.

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 em log de acesso usando o CloudFormation

Use o modelo do CloudFormation de exemplo a seguir para criar um grupo de logs do Amazon CloudWatch Logs e configurar o registro em log 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
      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