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