Configurar grupos de logs do CloudWatch - AWS Lambda
Permissões da função de execuçãoRegistro em log do CloudWatch para instâncias gerenciadas do Lambda

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. Também é possível 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.

É possível 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.

Alterar o grupo de logs de uma função (console)

  1. Abra a página Funções do console do Lambda.

  2. Escolha uma função.

  3. Na página de configuração da função, escolha Ferramentas de monitoramento e operações.

  4. No painel Configuração de registro em log, escolha Editar.

  5. No painel Grupo de logs do grupo de logs do CloudWatch, escolha Personalizado.

  6. Em Grupo de logs personalizado, insira o nome do grupo de logs do CloudWatch para o qual você deseja que sua função envie logs. Se você inserir o nome de um grupo de logs existente, sua função usará esse grupo. Se não existir nenhum grupo de logs com o nome inserido, o Lambda criará um novo grupo de logs para a função com esse nome.

Alterar o grupo de logs de uma função (AWS CLI)

  • Para alterar o grupo de logs de uma função existente, use o comando update-function-configuration.

    aws lambda update-function-configuration \
  --function-name myFunction \
  --logging-config LogGroup=myLogGroup
Especificar um grupo de logs personalizado ao criar uma função (AWS CLI)

  • Para especificar um grupo de logs personalizado ao criar uma nova função do Lambda usando a AWS CLI, use a opção --logging-config. O comando de exemplo a seguir cria uma função do Lambda para Node.js que envia logs para um grupo de logs denominado myLogGroup.

    aws lambda create-function \
  --function-name myFunction \
  --runtime nodejs24.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::123456789012:role/LambdaRole \
  --logging-config LogGroup=myLogGroup

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 sua função usando o console do Lambda, o Lambda adiciona essa permissão ao perfil de acordo com as seguintes condições:

  • O destino do serviço está definido como o CloudWatch Logs

  • O perfil de execução da função não tem permissões para carregar logs no CloudWatch Logs (o destino padrão)

nota

O Lambda não adiciona nenhuma permissão de Put para destinos de log do Amazon S3 ou Firehose.

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.

Registro em log do CloudWatch para instâncias gerenciadas do Lambda

Ao usar instâncias gerenciadas do Lambda, há outras considerações sobre o envio de logs ao CloudWatch Logs:

Requisitos de rede de VPC

As instâncias gerenciadas do Lambda são executadas em instâncias do EC2 de propriedade do cliente em sua VPC. Para enviar logs para o CloudWatch Logs e rastreamentos para o X-Ray, você deve garantir que essas APIs da AWS sejam roteáveis a partir da sua VPC. Você tem várias opções:

  • AWS PrivateLink (recomendado): use o AWS PrivateLink para criar endpoints da VPC para serviços do CloudWatch e do X-Ray. Isso permite que suas instâncias acessem esses serviços de forma privada, sem a necessidade de um gateway da Internet ou gateway de NAT. Para obter mais informações, consulte Uso do CloudWatch Logs com endpoints da VPC de interface.

  • Gateway de NAT: configure um gateway de NAT para permitir o acesso de saída à Internet a partir de suas sub-redes privadas.

  • Gateway da Internet: para sub-redes públicas, certifique-se de que sua VPC tenha um gateway da Internet configurado.

Se as APIs do CloudWatch Logs ou do X-Ray não forem roteáveis a partir da sua VPC, seus logs e rastreamentos de funções não serão entregues.

Invocações simultâneas e atribuição de logs

Os ambientes de execução das instâncias gerenciadas do Lambda podem processar várias invocações simultaneamente. Quando várias invocações são executadas simultaneamente, suas entradas de log são intercaladas no mesmo fluxo de log. Para filtrar e analisar com eficácia os logs de invocações simultâneas, é necessário garantir que cada entrada de log inclua o ID da solicitação da AWS.

Recomendamos uma das abordagens a seguir:

  • Use loggers de runtime padrão do Lambda (recomendado): as bibliotecas de registro em log padrão fornecidas pelos runtimes gerenciados do Lambda incluem automaticamente o ID da solicitação em cada entrada de log.

  • Implemente logs JSON estruturados: se você estiver criando um runtime personalizado ou precisar de um registro em log personalizado, implemente logs em formato JSON que incluam o ID da solicitação em cada entrada. As instâncias gerenciadas do Lambda oferecem suporte somente ao formato de log de JSON. Inclua o campo requestId em seus logs de JSON para habilitar a filtragem por invocação:

    {
  "timestamp": "2025-01-15T10:30:00.000Z",
  "level": "INFO",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Processing request"
}

Com a atribuição do ID da solicitação, é possível filtrar as entradas de log do CloudWatch Logs para uma invocação específica usando consultas do CloudWatch Logs Insights. Por exemplo:

fields @timestamp, @message
| filter requestId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
| sort @timestamp asc

Para obter mais informações sobre os requisitos de log das instâncias gerenciadas do Lambda, consulte Noções básicas sobre o ambiente de execução das instâncias gerenciadas do Lambda.