View a markdown version of this page

Criar uma entrega para logs de execução da API REST - Amazon API Gateway
Pré-requisitosValores específicos do API Gateway para a entrega do Amazon CloudWatch LogsCriar uma entrega de logs (AWS CLI)Campos de registroCriar uma entrega de logs (CloudFormation)Criar uma entrega de logs (console do API Gateway)

Criar uma entrega para logs de execução da API REST

É possível rotear os logs de execução para seus próprios grupos de logs do CloudWatch Logs, buckets do Amazon S3 ou fluxos do Firehose. Para fazer isso, crie uma entrega do Amazon CloudWatch Logs. Isso envolve três etapas: criar uma origem de entrega, criar um destino de entrega e vinculá-los a uma entrega.

Pré-requisitos

Antes de criar uma entrega de logs, verifique se você tem o seguinte:

  • Registro em log de execução habilitado no estágio da sua API REST. Defina loggingLevel como ERROR ou INFO. Se o registro em log não estiver habilitado, a criação da origem de entrega falhará.

  • Um recurso de destino: um grupo de logs do CloudWatch Logs, um bucket do Amazon S3 ou um fluxo do Firehose que você possui.

  • Permissões para chamar as APIs de entrega do Amazon CloudWatch Logs. Consulte mais informações em Habilitar o registro em log de serviços da AWS no Guia do usuário do Amazon CloudWatch Logs.

Valores específicos do API Gateway para a entrega do Amazon CloudWatch Logs

Ao criar uma entrega para os logs de execução do API Gateway, use os seguintes valores:

Atributo ARN

arn:aws:apigateway:{region}:{account-id}:/restapis/{rest-api-id}/stages/{stage-name}

Tipo de log

EXECUTION_LOGS

Criar uma entrega de logs (AWS CLI)

O exemplo a seguir cria uma entrega que envia os logs de execução de uma API REST para um grupo de logs do CloudWatch Logs que você possui.

  1. Criar a origem de entrega

    Registre sua API REST como a origem de entrega.

    aws logs put-delivery-source \
    --name my-apigw-source \
    --log-type EXECUTION_LOGS \
    --resource-arn arn:aws:apigateway:{region}:{account-id}:/restapis/{rest-api-id}/stages/{stage-name}
  2. Criar um destino de entrega

    Registre seu grupo de logs como o destino de entrega.

    aws logs put-delivery-destination \
    --name my-log-destination \
    --delivery-destination-configuration "destinationResourceArn=arn:aws:logs:{region}:{account-id}:log-group:{log-group-name}"
  3. Criar a entrega

    Vincule a origem ao destino.

    aws logs create-delivery \
    --delivery-source-name my-apigw-source \
    --delivery-destination-arn arn:aws:logs:{region}:{account-id}:delivery-destination:my-log-destination

Para enviar logs ao Amazon S3 ou Firehose, especifique o ARN do recurso apropriado no comando put-delivery-destination. Consulte mais informações sobre o fluxo de trabalho completo da entrega do Amazon CloudWatch Logs em Habilitar o registro em log de serviços da AWS no Guia do usuário do Amazon CloudWatch Logs.

Para enviar logs a vários destinos, crie entregas adicionais usando a mesma origem de entrega com destinos diferentes.

Campos de registro

Com a entrega do Amazon CloudWatch Logs, os logs de execução incluem campos estruturados que podem ser personalizados por destino. Os seguintes campos opcionais estão disponíveis:

  • resource_arn: o ARN do estágio da API

  • event_timestamp: o horário do evento de logs

  • api_id: o identificador da API REST

  • stage: o nome do estágio

  • resource_path: o caminho do recurso da solicitação

  • http_method: o método HTTP

  • payload: o conteúdo do log de execução (igual ao dos logs de execução padrão)

É possível selecionar quais campos incluir e o formato de saída para cada destino usando o parâmetro --record-fields em create-delivery e o parâmetro --output-format em put-delivery-destination.

Os formatos de saída disponíveis dependem do destino:

  • CloudWatch Logs: json, plain

  • Amazon S3: json, plain, w3c, parquet

  • Firehose: json, plain

Correspondência com a saída dos logs de execução padrão

Se você quiser uma saída de entrega que corresponda ao registro em log de execução padrão (somente carga útil, sem campos adicionais), adicione --output-format "plain" a put-delivery-destination e --record-fields "payload" --field-delimiter "" a create-delivery.

Criar uma entrega de logs (CloudFormation)

Ao montar o ARN do estágio para os modelos do CloudFormation, use o seguinte padrão:

  DeliverySource:
    Type: AWS::Logs::DeliverySource
    Properties:
      Name: my-apigw-source
      LogType: EXECUTION_LOGS
      ResourceArn: !Sub "arn:${AWS::Partition}:apigateway:${AWS::Region}:${AWS::AccountId}:/restapis/${MyApi}/stages/${MyStageName}"

Criar uma entrega de logs (console do API Gateway)

É possível criar uma entrega de logs na seção Logs e rastreamento da página de detalhes do estágio.

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

  2. Selecione sua API REST e, depois, escolha Estágios.

  3. Escolha um estágio.

  4. Na seção Logs e rastreamento, em Destinos de entrega de logs, selecione Adicionar destino.

  5. Escolha um tipo de destino (CloudWatch Logs, Amazon S3 ou Firehose) e especifique o recurso de destino.

  6. Escolha Salvar.

Importante

É necessário habilitar o registro em log de execução no estágio antes de adicionar destinos de entrega. Se o registro em log estiver definido como Desativado, a configuração de entrega não gerará logs.

nota

Para configurar destinos de entrega entre contas, use a AWS CLI. É necessário criar uma política de destino de entrega na conta de destino antes de criar a entrega na conta de origem. Consulte mais informações em Exemplo de entrega entre contas no Guia do usuário do Amazon CloudWatch Logs.