Registrar em log e monitorar funções do Lambda em Ruby

O AWS Lambda monitora automaticamente as funções do Lambda em seu nome e envia logs para o Amazon CloudWatch. Sua função do Lambda vem com um grupo de logs do CloudWatch Logs e uma transmissão de logs para cada instância de sua função. O ambiente do runtime do Lambda envia detalhes sobre cada invocação à transmissão de logs e transmite os logs e outras saídas do código de sua função. Para obter mais informações, consulte Enviar logs de função do Lambda para o CloudWatch Logs.

Esta página descreve como produzir saída em log usando o código de função do Lambda e como acessar os logs usando a AWS Command Line Interface, o console do Lambda ou o console do CloudWatch.

Criar uma função que retorna logs

Para gerar os logs do seu código de função, você pode usar instruções puts ou qualquer biblioteca de logs que grave no stdout ou no stderr. O exemplo a seguir registra em log os valores das variáveis de ambiente e o objeto do evento.

# lambda_function.rb

def handler(event:, context:)
    puts "## ENVIRONMENT VARIABLES"
    puts ENV.to_a
    puts "## EVENT"
    puts event.to_a
end

START RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Version: $LATEST
## ENVIRONMENT VARIABLES
environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]3893xmpl7fac4485b47bb75b671a283c', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...})
## EVENT
{'key': 'value'}
END RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95
REPORT RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95  Duration: 15.74 ms  Billed Duration: 147 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 130.49 ms
XRAY TraceId: 1-5e34a614-10bdxmplf1fb44f07bc535a1   SegmentId: 07f5xmpl2d1f6f85 Sampled: true   

O runtime do Ruby registra em log as linhas START, END e REPORT para cada invocação. A linha do relatório fornece os detalhes a seguir.

Para obter logs mais detalhados, use a Trabalhar com a biblioteca de registro em log do Ruby.

Uso de controles avançados de registro em log do Lambda com Ruby

Para dar mais controle sobre como os logs das funções são capturados, processados e consumidos, o Lambda oferece controles avançados de registro em log com Ruby. Para runtimes do Ruby 4.0 e versões posteriores, é possível configurar as seguintes opções de registro em log:

Para obter mais informações sobre essas opções de registro em log e instruções sobre como configurar a função para usá-las, consulte Configurar controles avançados de registro em log para funções do Lambda.

Para saber mais sobre como usar as opções de formato de log e nível de log com as funções do Lambda para Ruby, consulte as orientações nas seções a seguir.

Usar logs JSON estruturados com Ruby

Se você selecionar JSON para o formato de log da sua função, o Lambda enviará a saída de logs pela biblioteca Logger padrão do Ruby para o CloudWatch como JSON estruturado. Cada objeto de log JSON contém pelo menos quatro pares de valores-chave com as seguintes chaves:

A biblioteca Logger do Ruby também pode adicionar pares de valores de chave, como "logger", para esse objeto JSON.

Os exemplos nas seções a seguir mostram como as saídas de log geradas usando a biblioteca Logger do Ruby são capturadas no CloudWatch Logs quando você configura o formato de log da função como JSON.

Se você usar o método puts para produzir saídas básicas de log, conforme descrito em Criar uma função que retorna logs, o Lambda capturará essas saídas como texto simples, mesmo se o formato de log da função for configurado como JSON.

Saídas de log JSON padrão usando a biblioteca do Ruby Logger

O exemplo de trecho de código e saída de log a seguir mostra como as saídas de log padrão geradas usando a biblioteca Logger do Ruby são capturadas no CloudWatch Logs quando o formato de log da função é configurado como JSON.

require 'logger'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  logger.info("Inside the handler function")
end

{
    "timestamp": "2025-10-27T19:17:45.586Z",
    "level": "INFO",
    "message": "Inside the handler function",
    "requestId": "79b4f56e-95b1-4643-9700-2807f4e68189"
}

Registrar parâmetros extras em log JSON

Quando o formato de log da sua função está definido como JSON, você também pode registrar parâmetros adicionais em log com a biblioteca Logger do Ruby passando um hash de pares extras de valores-chave para a saída do log.

require 'logger'
require 'json'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  extra_params = { "a" => "b", "b" => [3] }
  logger.info({ message: "extra parameters example" }.merge(extra_params).to_json)
end

{
    "timestamp": "2025-11-02T15:26:28Z",
    "level": "INFO",
    "message": "extra parameters example",
    "requestId": "3dbd5759-65f6-45f8-8d7d-5bdc79a3bd01",
    "a": "b",
    "b": [
        3
    ]
}

Exceções de log em JSON

O trecho de código a seguir mostra como as exceções do Ruby são capturadas na saída de log da função quando o formato de log é configurado como JSON. Observe que as saídas de log geradas usando logger.error com uma exceção são designadas com o nível de log ERROR.

require 'logger'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  begin
    raise "exception"
  rescue => e
    logger.error(e)
  end
end

{
    "timestamp": "2025-11-02T16:18:57Z",
    "level": "ERROR",
    "message": "exception",
    "stackTrace": [
        "  /var/task/lambda_function.rb:4:in `lambda_handler'"
    ],
    "errorType": "RuntimeError",
    "errorMessage": "exception",
    "requestId": "3f9d155c-0f09-46b7-bdf1-e91dab220855",
    "location": "/var/task/lambda_function.rb:lambda_handler:6"
}

Usar a filtragem em nível de log com Ruby

Ao configurar a filtragem em nível de log, você pode optar por enviar somente logs de um determinado nível, ou inferior, para o CloudWatch Logs. Para saber como configurar a filtragem em nível de log para a função, consulte Filtragem em nível de log.

Para o AWS Lambda filtrar os logs de aplicação de acordo com o nível de log, a função precisa usar logs em formato JSON. Isso pode ser feito de duas maneiras:

Também é possível usar uma instrução puts para gerar um objeto JSON que contenha um identificador de nível de log. A instrução puts a seguir produz uma saída em formato JSON em que o nível do log é definido como INFO. O AWS Lambda enviará o objeto JSON para o CloudWatch Logs se o nível de registro em log da função estiver definido como INFO, DEBUG ou TRACE.

puts '{"msg":"My log message", "level":"info"}'

Para que o Lambda filtre os logs da função, você também precisa incluir um par de valores-chave "timestamp" na saída do log JSON. A hora deve ser especificada 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.

Uso de uma biblioteca de registro em log alternativa

Se precisar usar uma versão personalizada da biblioteca do logger, você pode incluí-la em seu pacote de implantação ou em uma camada Lambda e definir a variável de ambiente RUBYLIB como diretório lib da biblioteca. O runtime do Lambda carregará sua versão, em vez da versão incluída.

Se o código já usa outra biblioteca de registro em log para produzir logs JSON estruturados, você não precisará fazer nenhuma alteração. O AWS Lambda não codifica duas vezes nenhum log que já esteja codificado em JSON. Mesmo que a função seja configurada para usar logs em formato JSON, suas saídas de log serão exibidas no CloudWatch com a estrutura JSON que você definiu.

Visualizar logs no console do Lambda

É possível usar o console do Lambda para exibir a saída do log depois de invocar uma função do Lambda.

Se seu código puder ser testado no editor de Código incorporado, você encontrará logs nos resultados de execução. Ao usar o recurso de teste do console para invocar uma função, você encontrará Saída de log na seção Detalhes.

Visualização de logs no console do CloudWatch

É possível usar o console do Amazon CloudWatch para exibir logs de todas as invocações da função do Lambda.

Cada fluxo de log corresponde a uma instância da sua função. Um fluxo de logs é exibido quando você atualiza sua função do Lambda e quando mais instâncias são criadas para lidar com invocações simultâneas. Para localizar logs de uma invocação específica, recomendamos intrumentar sua função com AWS X-Ray. O X-Ray registra detalhes sobre a solicitação e o stream de logs no rastreamento.

Visualizar logs usando a AWS Command Line Interface (AWS CLI)

O AWS CLI é uma ferramenta de código aberto que permite interagir com os serviços do AWS usando comandos no shell da linha de comando. Para concluir as etapas desta seção, você deve ter a versão 2 da AWS CLI.

É possível usar a AWS CLI para recuperar logs de uma invocação usando a opção de comando --log-type. A resposta contém um campo LogResult com até 4 KB de logs codificados em base64 obtidos da invocação.

aws lambda invoke --function-name my-function out --log-type Tail

{
    "StatusCode": 200,
    "LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
    "ExecutedVersion": "$LATEST"
}

aws lambda invoke --function-name my-function out --log-type Tail \
--query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode

START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST
"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8
REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8  Duration: 79.67 ms      Billed Duration: 80 ms         Memory Size: 128 MB     Max Memory Used: 73 MB

#!/bin/bash
aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out
sed -i'' -e 's/"//g' out
sleep 15
aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5

chmod -R 755 get-logs.sh

./get-logs.sh

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}
{
    "events": [
        {
            "timestamp": 1559763003171,
            "message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n",
            "ingestionTime": 1559763003309
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r  \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r  \"key\": \"value\"\r}\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n",
            "ingestionTime": 1559763018353
        }
    ],
    "nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795",
    "nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080"
}

Excluir logs

Os grupos de logs não são excluídos automaticamente excluídos quando você exclui uma função. Para evitar armazenar logs indefinidamente, exclua o grupo de logs ouconfigurar um período de retençãoapós o qual os logs são excluídos automaticamente.

Trabalhar com a biblioteca de registro em log do Ruby

A biblioteca do logger do Ruby retorna logs simplificados que são facilmente lidos. Use o utilitário logger para gerar informações detalhadas, mensagens e códigos de erro relacionados à sua função.

# lambda_function.rb

require 'logger'

def handler(event:, context:) 
  logger = Logger.new($stdout)
  logger.info('## ENVIRONMENT VARIABLES')
  logger.info(ENV.to_a)
  logger.info('## EVENT')
  logger.info(event)
  event.to_a
end

A saída de logger inclui o nível do log, o timestamp e o ID da solicitação.

START RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 Version: $LATEST
[INFO]  2020-01-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## ENVIRONMENT VARIABLES

[INFO]  2020-01-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]1bbe51xmplb34a2788dbaa7433b0aa4d', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...})

[INFO]  2020-01-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## EVENT

[INFO]  2020-01-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    {'key': 'value'}

END RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125
REPORT RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125  Duration: 2.75 ms   Billed Duration: 117 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 113.51 ms
XRAY TraceId: 1-5e34a66a-474xmpl7c2534a87870b4370   SegmentId: 073cxmpl3e442861 Sampled: true