Personalize os destinos do Amazon API Gateway para logs de execução

Por Giedrius Praspaliauskas, Arquiteto de Soluções Especialista Sênior em Serverless e Udit Parikh, Sr. Cloud Support Engineer na Amazon Web Services.

Amazon API Gateway os logs de execução ajudam você a rastrear o processamento de requisições passo a passo através dos stages da sua REST API. Eles capturam resultados de autorização, latência de integração, saída de mapping template e detalhes de erros que de outra forma seriam invisíveis na superfície da API. Quando uma requisição de produção falha de uma forma que o access log não consegue explicar, o log de execução é geralmente onde você encontra a explicação.

Até agora, os logs de execução tinham duas restrições. Cada evento de log era truncado em 1 KB, então uma requisição com um corpo JSON de tamanho moderado excederia esse limite e o restante era descartado. Os logs só podiam ir para o grupo de logs gerenciado automaticamente que o API Gateway cria para você (API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}).

With Amazon CloudWatch a entrega de Logs para logs de execução de REST API, agora você pode direcionar os logs de execução para o Amazon CloudWatch Logs, Amazon Simple Storage Service (Amazon S3), or Amazon Data Firehose. Os eventos de log podem ter até 1 MB por entrada, e você se beneficia dos preços de logs fornecidos.

Nesta publicação, você aprende como a entrega do CloudWatch Logs funciona com os logs de execução do API Gateway, como configurá-la e quais padrões funcionam melhor para cenários comuns de observabilidade.

Entendendo os logs de execução do API Gateway

O API Gateway produz duas categorias de logs: logs de acesso e logs de execução. Os logs de acesso registram uma linha de resumo por requisição, semelhante a um log de acesso de servidor HTTP. Você configura o formato e o destino por conta própria.

Os logs de execução são diferentes. Eles capturam o processamento interno de cada requisição à medida que ela passa pelo pipeline do API Gateway: avaliação do autorizador, validação da requisição, despacho de integração, mapeamento de resposta e tratamento de erros. Esses logs existem para que você possa responder a perguntas como “por que meu autorizador rejeitou esse token?” ou “o que o mapping template produziu antes de chegar à minha integração de backend?”

O API Gateway gerencia a criação de logs de execução automaticamente. Quando você define loggingLevel to INFO or ERROR nas configurações de método do seu stage, o serviço grava eventos de log de execução em um grupo de logs do CloudWatch Logs que ele gerencia em seu nome. Você não escolhe o nome do grupo de logs nem configura a retenção diretamente nele.

O modelo gerenciado automaticamente funciona para muitos clientes, mas pode gerar atrito para equipes com requisitos específicos de observabilidade. Frameworks de conformidade que exigem logs no S3 com uma estrutura de prefixo específica precisam de um filtro de assinatura e mecanismo de entrega adicional. Enviar logs de execução para uma ferramenta de gerenciamento de informações e eventos de segurança (SIEM) por meio de um stream do Firehose requer uma camada de encaminhamento.

Entrega configurável de logs com o CloudWatch Logs

A entrega do CloudWatch Logs separa o roteamento de logs do conteúdo de logs. Dois conceitos controlam o comportamento:

DeliverySource tem como escopo o ARN do stage do seu API Gateway. Ele define para onde os logs vão. Você cria uma fonte de entrega e, em seguida, anexa um ou mais destinos de entrega (grupo de logs do CloudWatch Logs, bucket S3 ou stream do Firehose).

MethodSettings controla o que é registrado. A configuração loggingLevel setting (INFO, ERROR, or OFF) and dataTraceEnabled ainda determinam quais eventos de log o API Gateway produz. Essas configurações funcionam da mesma forma, independentemente de você usar o grupo de logs gerenciado automaticamente ou a entrega do CloudWatch Logs.

Quando você cria uma entrega com o uso de as APIs do CloudWatch Logs, o CloudWatch Logs ativa a entrega de logs no stage do seu API Gateway. Quando você exclui a entrega, o CloudWatch Logs a desativa de acordo. Você não precisa alterar nenhuma flag no lado do API Gateway, e os logs de execução voltam automaticamente a fluir para o grupo de logs gerenciado automaticamente.

Suas configurações de método existentes mantêm seu significado. Os valores de loggingLevel and dataTraceEnabled continuam a controlar o conteúdo dos logs. Se loggingLevel já estiver definido como INFO or ERROR, a criação de uma entrega redireciona esses logs para o destino escolhido sem nenhuma configuração adicional.

O diagrama a seguir mostra como as peças se encaixam.

Diagrama mostrando uma fonte de entrega de stage do API Gateway distribuindo para destinos do CloudWatch Logs, Amazon S3 e Firehose.

Figura 1 — Uma única fonte de entrega com escopo em um stage do API Gateway alimenta uma ou mais entregas, cada uma das quais grava em um destino de entrega apoiado pelo CloudWatch Logs, Amazon S3 ou Amazon Data Firehose

A tabela a seguir resume o que muda quando a entrega de logs está ativa.

Aspecto	Registro de execução padrão	Entrega de logs
Destino	Grupo de logs gerenciado automaticamente do CloudWatch Logs	CloudWatch Logs, Amazon S3 ou Firehose
Múltiplos destinos	Não	Sim
Preços	Ingestão padrão do CloudWatch Logs	Preços de logs fornecidos
Tamanho do evento de log	Truncado em 1 KB	Até 1 MB
Configuração	Set `loggingLevel` em MethodSettings	Criar entrega através das APIs do CloudWatch Logs
Remoção	Set `loggingLevel` to `OFF`	Excluir entrega

O que permanece igual

Apenas o roteamento de logs de execução muda. Os logs de acesso continuam a fluir através de accessLogSettings para qualquer grupo de logs que você configurar, e recursos do stage não relacionados, como rastreamento do AWS X-Ray, métricas detalhadas do CloudWatch, limitação de taxa e cache, se comportam exatamente como antes.

Opções de configuração e integração

Antes de criar uma entrega, confirme os seguintes requisitos:

A REST API do API Gateway está implantada em um stage.
loggingLevel is set to INFO or ERROR in MethodSettings.
A função IAM do CloudWatch Logs no nível da conta está configurada. Para as etapas de configuração, consulte Configurar o registro do CloudWatch para REST APIs no API Gateway.
Para entrega entre contas, o destino tem uma política de recursos apropriada anexada por meio de PutDeliveryDestinationPolicy.

Enviando logs para um grupo de logs personalizado do CloudWatch Logs

O ponto de partida mais comum é redirecionar os logs de execução para um grupo de logs que você possui. Você obtém controle direto sobre políticas de retenção, filtros de métricas e filtros de assinatura. As etapas a seguir usam a AWS Command Line Interface (AWS CLI) com o ID fictício da REST API abc123, stage prod, Region us-east-1, and account 111122223333.

Crie uma fonte de entrega referenciado como o ARN do seu stage. O tipo de log para logs de execução da REST API é EXECUTION_LOGS:

aws logs put-delivery-source \
    --name my-apigw-execution-logs \
    --resource-arn arn:aws:apigateway:us-east-1:111122223333:/restapis/abc123/stages/prod \
    --log-type EXECUTION_LOGS

Crie um destino de entrega apontar para seu grupo de logs personalizado (existente) e, em seguida, crie a entrega que os conecta:

aws logs put-delivery-destination \
    --name my-execution-log-destination \
    --delivery-destination-configuration \
        destinationResourceArn=arn:aws:logs:us-east-1:111122223333:log-group:/my-api/execution-logs

aws logs create-delivery \
    --delivery-source-name my-apigw-execution-logs \
    --delivery-destination-arn arn:aws:logs:us-east-1:111122223333:delivery-destination:my-execution-log-destination

Verifique se a entrega está ativa listando as entregas da fonte:
```
aws logs describe-deliveries
```
Bash

A resposta inclui o ID da entrega, a fonte e o ARN do destino após a entrega ser estabelecida. Os logs de execução fluem para /my-api/execution-logs em vez do grupo gerenciado automaticamente.

Note: A entrega de logs adiciona campos estruturados (resource_arn, event_timestamp, api_id, stage, resource_path, http_method, and payload) a cada evento, portanto, uma nova entrega emite mais do que seus logs anteriores. Para manter o formato tradicional de log de execução sem nada extra, defina o formato de saída e os campos de registro ao criar o destino de entrega e a entrega:

aws logs put-delivery-destination \
    --output-format "plain" ...

aws logs create-delivery \
    --record-fields "payload" \
    --field-delimiter "" ...

Roteando logs para o Amazon S3

O S3 funciona bem para retenção de longo prazo com custo menor, ou para alimentar logs em ferramentas de análise, como o Amazon Athena. O bucket deve estar na mesma região da sua API. Crie um destino de entrega apontar para o seu bucket:

aws logs put-delivery-destination \
    --name s3-archive-destination \
    --delivery-destination-configuration \
        destinationResourceArn=arn:aws:s3:::amzn-s3-demo-apigw-logs

Em seguida, crie uma entrega com o uso de o mesmo nome da fonte. O CloudWatch Logs entrega os eventos para o seu bucket, onde você pode consultá-los com o Athena ou catalogá-los com o AWS Glue.

Transmitindo para o Amazon Data Firehose

Para pipelines de análise em tempo real ou integração com SIEM de terceiros, a entrega do Firehose envia eventos de log de execução diretamente para o seu stream. A configuração é idêntica: crie um destino de entrega com o ARN do stream do Firehose e, em seguida, crie uma entrega. Com a entrega direta do Firehose, você não precisa mais manter filtros de assinatura do CloudWatch Logs e AWS Lambda para rotear logs de execução para sistemas de análise externos.

Entrega para múltiplos destinos e formatação por destino

Uma única fonte de entrega suporta múltiplos destinos. Você pode direcionar os mesmos logs de execução para o CloudWatch Logs para alertas em tempo real, S3 para retenção de conformidade de longo prazo e Firehose para o seu SIEM, tudo a partir de um único stage. Crie entregas adicionais com o uso de a mesma fonte de entrega com ARNs de destino diferentes.

Cada destino recebe eventos de log idênticos. Para moldar o que chega a cada destino, aplique um filtro de assinatura do CloudWatch Logs no destino do CloudWatch Logs. Por exemplo, você pode encaminhar apenas eventos de nível ERRORpara uma função Lambda que envia alertas para um SIEM, enquanto a mesma fonte de entrega grava o stream de eventos completo no S3 para conformidade.

Experiência no console de gerenciamento

Você também pode adicionar um destino de entrega de logs no console de gerenciamento depois de ativar o registro para o stage.

Console do API Gateway mostrando a opção de adicionar um destino de entrega de logs depois que o registro é ativado para o stage.

Você pode especificar múltiplos destinos, tanto na conta atual quanto em uma conta diferente:

Console do API Gateway mostrando múltiplos destinos de entrega configurados, incluindo opções entre contas.

Mantendo o monitoramento existente intacto

Se você tem dashboards ou alarmes no grupo de logs gerenciado automaticamente, use esse mesmo grupo de logs como um dos seus destinos de entrega. Seu monitoramento existente continua funcionando e você ganha a capacidade de enviar logs para destinos adicionais, como S3 ou Firehose, em paralelo.

Melhores práticas

Atualize dashboards e alarmes antes de ativar a entrega de logs. Quando você ativa a entrega de logs, o grupo de logs gerenciado automaticamente para de receber logs. Quaisquer alarmes do CloudWatch, dashboards ou regras do Contributor Insights apontar para API-Gateway-Execution-Logs_{rest-api-id}/{stage_name} param de funcionar. Migre essas referências para o seu novo grupo de logs antes de criar a entrega.

Keep loggingLevel at INFO or ERROR. A entrega de logs controla o roteamento, não o conteúdo. Se loggingLevel is OFF, nenhum evento de log de execução é produzido, independentemente de existir uma entrega. Verifique as configurações de método antes de solucionar problemas de logs ausentes.

Trate a capacidade de evento de log de 1 MB como uma decisão de segurança, não apenas uma conveniência de depuração. Com dataTraceEnabled definido como verdadeiro, os logs de execução incluem payloads completos de requisição e resposta de até 1 MB. Esses payloads podem conter informações de identificação pessoal (PII) ou outros dados sensíveis. Confirme que seus destinos de log possuem controles de acesso, criptografia e políticas de retenção apropriados. Mascare ou filtre campos sensíveis nos mapping templates antes do registro e ative o rastreamento de dados seletivamente por método ou apenas em stages de não produção.

Comece com um único destino e depois expanda. Valide que seu grupo de logs ou bucket recebe eventos corretamente antes de adicionar o Firehose ou destinos adicionais.

A entrega de logs é com base no melhor esforço. Em casos raros, alguns eventos de log podem não ser entregues. Para cargas de trabalho críticas para auditoria, construa retenção e reconciliação que considerem eventos ocasionalmente ausentes, em vez de tratar os logs de execução como o sistema de registro.

Limpeza

Para evitar cobranças contínuas dos recursos que você criou ao seguir esta publicação, exclua a entrega e depois remova os destinos e qualquer bucket S3 de exemplo ou stream de entrega do Data Firehose que você não precisa mais. Excluir a entrega retorna o stage ao registro gerenciado automaticamente padrão.

aws logs delete-delivery --id <delivery-id>

Quando a entrega é excluída, o CloudWatch Logs desativa a entrega de logs no stage do API Gateway automaticamente. A fonte de entrega e o destino de entrega permanecem como objetos independentes. Exclua-os com delete-delivery-source and delete-delivery-destination se você não planeja reutilizá-los.

Conclusão

CloudWatch Logs delivery for API Gateway REST API execution logs helps address the 1 KB event truncation and single managed destination constraints. You can now route full execution logs to CloudWatch Logs, Amazon S3, or Amazon Data Firehose, use multiple destinations from a single stage, and pay preços de logs fornecidos.

O recurso funciona junto com as configurações de método existentes. Nenhuma alteração na sua configuração de registro atual é necessária além de criar a entrega em si.

Para começar, consulte Rotear logs de execução com a entrega do Amazon CloudWatch Logs na documentação do API Gateway. Para mais informações sobre a configuração de entrega do CloudWatch Logs, consulte Ativar registro de serviços da AWS. Para detalhes de preços, consulte a página de preços do Amazon CloudWatch. Experimente em um stage de teste e compartilhe sua experiência nos comentários.

Este conteúdo foi traduzido da publicação original do blog, que pode ser encontrada aqui.

Biografia do Autores

	Giedrius Praspaliauskas é Arquiteto de Soluções Especialista Sênior em Serverless na Amazon Web Services.
	Udit Parikh é Senior Cloud Support Engineer na Amazon Web Services.

Biografia do tradutores

Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem.
https://www.linkedin.com/in/danielabib/

Nicolas Tarzia é Senior Technical Account Manager na AWS, com mais de 13 anos de experiência, com ampla experiência em arquitetura cloud, engenharia e design de software. Atualmente está habilitando empresas do ramo de ISV (Independent Software Vendors) simplificando a operação na nuvem e otimizando os custos em cloud. Sua área de interesse são tecnologias serverless.
https://www.linkedin.com/in/nicolastarzia

O blog da AWS