Configurar controles avançados de registro em log para funções do Lambda

Para dar mais controle sobre como os logs das funções são capturados, processados e consumidos, o Lambda oferece as seguintes opções de configuração de log:

Para saber mais sobre a configuração de controles avançados de registro em log, consulte as seguintes seções:

Configurar logs em formato de texto simples e JSON

Capturar as saídas de log como pares de valores-chave JSON facilita a pesquisa e a filtragem ao depurar suas funções. Com os logs em formato JSON, você também pode adicionar tags e informações contextuais aos logs. Esse recurso ajuda a realizar análises automatizadas de grandes volumes de dados de log. A menos que o fluxo de trabalho de desenvolvimento dependa de ferramentas existentes que consumam logs do Lambda em texto simples, recomendamos que você selecione JSON para o formato de log.

Para todos os runtimes gerenciados pelo Lambda, você pode escolher se os logs do sistema da função são enviados para o CloudWatch Logs em texto simples não estruturado ou no formato JSON. Os logs do sistema são os logs que o Lambda gera e, às vezes, são conhecidos como logs de eventos da plataforma.

Para runtimes compatíveis, quando você usa um dos métodos de registro em log integrado compatível, o Lambda também pode gerar os logs de aplicações da função (os logs gerados pelo código da função) no formato JSON estruturado. Quando você configura o formato de log da função para esses runtimes, a configuração escolhida se aplica aos logs do sistema e de aplicações.

Para runtimes compatíveis, se a função usar uma biblioteca ou um método de registro em log compatível, você não precisa fazer nenhuma alteração no código existente para que o Lambda capture registros em JSON estruturado.

Runtimes e métodos de registro em log compatíveis

Atualmente, o Lambda é compatível com a opção de gerar logs de aplicações em JSON estruturado para os runtimes a seguir.

Para que o Lambda envie os logs de aplicações da função para o CloudWatch no formato JSON estruturado, sua função precisa usar as seguintes ferramentas de registro em log integradas para gerar logs:

Para obter mais informações sobre o uso de controles avançados de registro em log com runtimes compatíveis, consulte Registrar em log e monitorar funções do Lambda em Java, Registrar em log e monitorar funções do Lambda em Node.js e Registrar em log e monitorar funções do Lambda em Python.

Para outros runtimes gerenciados do Lambda, ele atualmente só tem compatibilidade nativa com a captura de logs do sistema no formato JSON estruturado. No entanto, você ainda pode capturar logs de aplicações no formato JSON estruturado em qualquer runtime usando ferramentas de registro em log, como o Powertools para AWS Lambda, que gera logs no formato JSON.

Formatos de log padrão

Atualmente, o formato de log padrão para todos os runtimes do Lambda é texto simples.

Se você já usa bibliotecas de registro em log, como o Powertools para AWS Lambda, para gerar logs de funções no formato JSON estruturado, não precisará alterar o código se selecionar log no formato JSON. O Lambda não codifica duas vezes nenhum log que já esteja codificado em JSON. Então, os logs de aplicações da função continuarão sendo capturados como antes.

Formato JSON para logs do sistema

Quando você configura o formato de log da função como JSON, cada item de log do sistema (evento de plataforma) é capturado como um objeto JSON que contém pares de valores-chave com as seguintes chaves:

O formato do valor "record" varia de acordo com o tipo de evento que está sendo registrado em log. Para ter mais informações, consulte Tipos de objeto Event da API de telemetria. Para obter mais informações sobre os níveis de log atribuídos aos eventos de log do sistema, consulte Mapeamento de eventos no nível de log do sistema.

Para comparação, os dois exemplos a seguir mostram a mesma saída de log nos formatos de texto simples e JSON estruturado. Observe que, na maioria dos casos, os eventos de log do sistema contêm mais informações quando enviados no formato JSON do que quando enviados em texto simples.

2024-03-13 18:56:24.046000 fbe8c1   INIT_START  Runtime Version: python:3.12.v18  Runtime Version ARN: arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0

{
  "time": "2024-03-13T18:56:24.046Z",
  "type": "platform.initStart",
  "record": {
    "initializationType": "on-demand",
    "phase": "init",
    "runtimeVersion": "python:3.12.v18",
    "runtimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0"
  }
}

Formato JSON para logs de aplicações

Quando você configura o formato de log da função como JSON, as saídas de logs de aplicações gravadas usando bibliotecas e métodos de registro em log compatíveis são capturadas como um objeto JSON que contém pares de valores de chave com as chaves a seguir.

Dependendo do runtime e do método de registro em log que a função usa, esse objeto JSON também pode conter pares de chaves adicionais. Por exemplo, em Node.js, se a função usa métodos do console para registrar em log objetos de erro usando vários argumentos, o objeto JSON conterá pares adicionais de valores de chave com as chaves errorMessage, errorType e stackTrace. Para saber mais sobre logs formatados em JSON em diferentes runtimes do Lambda, consulte Registrar em log e monitorar funções do Lambda em Python, Registrar em log e monitorar funções do Lambda em Node.js e Registrar em log e monitorar funções do Lambda em Java.

Para comparação, os dois exemplos a seguir mostram a mesma saída de log nos formatos de texto simples e JSON estruturado.

2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message

{
    "timestamp":"2024-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"some log message",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}

Configurar o formato de log da função

Para configurar o formato de log da função, você pode usar o console do Lambda ou a AWS Command Line Interface (AWS CLI). Você também pode configurar o formato de log de uma função usando os comandos CreateFunction e UpdateFunctionConfiguration da API do Lambda, o recurso AWS::Serverless::Function do AWS Serverless Application Model (AWS SAM) e o recurso AWS::Lambda::Function do AWS CloudFormation.

Alterar o formato de log da função não afeta os logs existentes armazenados no CloudWatch Logs. Somente os novos logs usarão o formato atualizado.

Se você alterar o formato de log da função para JSON e não definir o nível do log, o Lambda definirá automaticamente o nível do log da aplicação e do sistema da função como INFO. Isso significa que o Lambda só envia saídas de log de nível WARN e inferiores para o CloudWatch Logs. Para saber mais sobre a filtragem em nível de log da aplicação e do sistema, consulte Filtragem em nível de log

Para funções do Node.js que emitem logs de formato de métricas incorporadas (EMF), alterar o formato de log da função para JSON pode fazer com que o CloudWatch não consiga reconhecer as métricas.

Filtragem em nível de log

O Lambda pode filtrar os logs da função para que somente logs de um determinado nível de detalhes, ou de um nível inferior, sejam enviados para o CloudWatch Logs. Você pode configurar a filtragem em nível de logs separadamente para os logs do sistema da função (logs gerados pelo Lambda) e os logs de aplicações (logs gerados pelo código da função).

Para Runtimes e métodos de registro em log compatíveis, você não precisa fazer nenhuma alteração no código da função do Lambda para filtrar logs de aplicações da função.

Para todos os outros runtimes e métodos de registro em log, o código da função deve gerar eventos de log para stdout ou stderr como objetos formatados em JSON que contenham um par de valores-chave com a chave "level". Por exemplo, o Lambda interpreta a saída a seguir stdout como um log de nível DEBUG.

print('{"level": "debug", "msg": "my debug log", "timestamp": "2024-11-02T16:51:31.587199Z"}')

Se o campo de valor "level" for inválido ou estiver ausente, o Lambda atribuirá à saída do log o nível INFO. Para que o Lambda use o campo de carimbo de data/hora, você precisa especificar a hora em um formato RFC 3339 válido de carimbo de data/hora. Se você não fornecer um carimbo de data/hora válido, o Lambda atribuirá ao log o nível INFO e adicionará um carimbo de data/hora.

Ao denominar a chave de carimbo de data/hora, siga as convenções do runtime que estiver usando. O Lambda é compatível com as convenções de nomenclatura mais comuns usadas pelos runtimes gerenciados.

Para logs de aplicações (logs gerados pelo código da função), você pode escolher entre os níveis de log a seguir.

Quando você seleciona um nível de log, o Lambda envia logs desse nível, e de níveis inferiores, para o CloudWatch Logs. Por exemplo, se você definir o nível de log de aplicações de uma função como WARN, o Lambda não enviará saídas de log nos níveis INFO e DEBUG. O nível padrão de logs de aplicações para a filtragem de logs é INFO.

Quando o Lambda filtra os logs de aplicações da função, as mensagens de log sem nível receberão o nível INFO.

Para logs do sistema (logs gerados pelo serviço Lambda), você pode escolher entre os níveis de log a seguir.

Quando você seleciona um nível de log, o Lambda envia logs desse nível, e de níveis inferiores. Por exemplo, se você definir o nível de log do sistema de uma função como INFO, o Lambda não enviará saídas de log no nível DEBUG.

Por padrão, o Lambda define o nível de log do sistema como INFO. Com essa configuração, o Lambda envia automaticamente as mensagens de log "start" e "report" para o CloudWatch. Para receber logs do sistema mais ou menos detalhados, altere o nível de log para DEBUG ou WARN. Para ver uma lista dos níveis de log para os quais o Lambda mapeia diferentes eventos de log do sistema, consulte Mapeamento de eventos no nível de log do sistema.

Configurar a filtragem em nível de log

Para configurar a filtragem em nível de log de aplicações e do sistema para a função, você pode usar o console do Lambda ou a AWS Command Line Interface (AWS CLI). Você também pode configurar o nível de log de uma função usando os comandos CreateFunction e UpdateFunctionConfiguration da API do Lambda, o recurso AWS::Serverless::Function do AWS Serverless Application Model (AWS SAM) e o recurso AWS::Lambda::Function do AWS CloudFormation.

Observe que, se você definir o nível de log da função no código, essa definição terá precedência sobre qualquer outra configuração de nível de log que você definir. Por exemplo, se você usar o método logging setLevel() do Python para definir o nível de registro em log da sua função como INFO, essa definição terá precedência sobre uma configuração de WARN que você definir usando o console do Lambda.

Mapeamento de eventos no nível de log do sistema

Para eventos de log no nível do sistema gerados pelo Lambda, a tabela a seguir define o nível de log atribuído a cada evento. Para saber mais sobre os eventos listados na tabela, consulte Referência de esquema para Event da API de Telemetria do Lambda.

Filtragem em nível de log de aplicações com runtimes personalizados

Quando você configura a filtragem em nível de log de aplicações para a função, o Lambda define o nível de log de aplicações em segundo plano no runtime usando a variável de ambiente AWS_LAMBDA_LOG_LEVEL. O Lambda também define o formato de log da função usando a variável de ambiente AWS_LAMBDA_LOG_FORMAT. Você pode usar essas variáveis para integrar os controles avançados de registro em log do Lambda em um runtime personalizado.

Para definir as configurações de registro em log de uma função usando um runtime personalizado com o console, a AWS CLI e as APIs do Lambda, configure o runtime personalizado para verificar o valor dessas variáveis de ambiente. Depois disso, você pode configurar os loggers do runtime de acordo com o formato e os níveis de log selecionados.

Configurar grupos de logs do CloudWatch

Por padrão, o CloudWatch cria automaticamente um grupo de logs denominado /aws/lambda/<function name> para a função quando ela é invocada pela primeira vez. Para configurar a função para enviar logs a um grupo de logs existente ou para criar um novo grupo de logs para a função, você pode usar a AWS CLI ou o console do Lambda. Você também pode configurar grupos de logs personalizados usando os comandos CreateFunction e UpdateFunctionConfiguration da API do Lambda e o recurso do AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function.

Você pode configurar várias funções do Lambda para enviar logs ao mesmo grupo de logs do CloudWatch. Por exemplo, é possível usar um único grupo de logs para armazenar os logs de todas as funções do Lambda que fizerem parte de uma aplicação específica. Quando você usa um grupo de logs personalizado para uma função do Lambda, os fluxos de log criados pelo Lambda incluem o nome e a versão da função. Isso garante que o mapeamento entre mensagens de log e funções seja preservado, mesmo se você usar o mesmo grupo de logs para várias funções.

O formato de nomenclatura de fluxos de logs para grupos de logs personalizados segue esta convenção:

YYYY/MM/DD/<function_name>[<function_version>][<execution_environment_GUID>]

Observe que, ao configurar um grupo de logs personalizado, o nome selecionado para o grupo de logs deve seguir as regras de nomenclatura do CloudWatch Logs. Além disso, nomes de grupos de logs personalizados não devem começar com a string aws/. Se você criar um grupo de logs personalizado começando com aws/, o Lambda não conseguirá criar o grupo de logs. Como resultado, os logs da função não serão enviados para o CloudWatch.

Permissões da função de execução

Para que sua função envie logs para o CloudWatch Logs, ela precisa ter a permissão logs:PutLogEvents. Quando você configura o grupo de logs da função usando o console do Lambda, se a função não tiver essa permissão, o Lambda a adiciona por padrão ao perfil de execução da função. Quando o Lambda adiciona essa permissão, ele dá à função permissão para enviar logs para qualquer grupo de logs do CloudWatch Logs.

Para evitar que o Lambda atualize automaticamente o perfil de execução da função e o edite manualmente, expanda Permissões e desmarque Adicionar permissões necessárias.

Quando você configura o grupo de logs da função usando a AWS CLI, o Lambda não adiciona automaticamente a permissão logs:PutLogEvents. Adicione a permissão ao perfil de execução da função, caso isso ainda não tenha sido feito. Essa permissão está incluída na política gerenciada AWSLambdaBasicExecutionRole.