# 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](monitoring-cloudwatchlogs.md).
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.
**Topics**
+ [Criar uma função que retorna logs](#ruby-logging-output)
+ [Uso de controles avançados de registro em log do Lambda com Ruby](#ruby-logging-advanced)
+ [Visualizar logs no console do Lambda](#ruby-logging-console)
+ [Visualização de logs no console do CloudWatch](#ruby-logging-cwconsole)
+ [Visualizar logs usando a AWS Command Line Interface (AWS CLI)](#ruby-logging-cli)
+ [Excluir logs](#ruby-logging-delete)
+ [Trabalhar com a biblioteca de registro em log do Ruby](#ruby-logging-lib)
## 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.
**Example lambda\_function.rb**
```
# lambda_function.rb
def handler(event:, context:)
puts "## ENVIRONMENT VARIABLES"
puts ENV.to_a
puts "## EVENT"
puts event.to_a
end
```
**Example formato do log**
```
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.
**RELATAR campos de dados de linha**
+ **RequestId**: o ID de solicitação exclusivo para a invocação.
+ **Duração**: a quantidade de tempo que o método de manipulador da função gastou processando o evento.
+ **Duração faturada**: a quantia de tempo faturada para a invocação.
+ **Tamanho da memória**: a quantidade de memória alocada para a função.
+ **Memória máxima utilizada**: a quantidade de memória utilizada pela função. Quando as invocações compartilham um ambiente de execução, o Lambda relata a memória máxima usada em todas as invocações. Esse comportamento pode resultar em um valor relatado maior do que o esperado.
+ **Duração inicial**: para a primeira solicitação atendida, a quantidade de tempo que o runtime levou para carregar a função e executar o código fora do método do handler.
+ **XRAY TraceId**: para solicitações rastreadas, o [ID de rastreamento do AWS X-Ray](services-xray.md).
+ **SegmentId**: para solicitações rastreadas, o ID do segmento do X-Ray.
+ **Amostragem**: para solicitações rastreadas, o resultado da amostragem.
Para obter logs mais detalhados, use a [Trabalhar com a biblioteca de registro em log do Ruby](#ruby-logging-lib).
## 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:
+ **Formato do log**: selecione entre texto simples e formato JSON estruturado para os logs da sua função.
+ **Nível de log**: para logs no formato JSON, escolha o nível de detalhe dos logs enviados pelo Lambda para o Amazon CloudWatch, como ERROR, DEBUG ou INFO.
+ **Grupo de logs**: escolha o grupo de logs do CloudWatch para o qual sua função envia logs.
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](monitoring-logs.md#monitoring-cloudwatchlogs-advanced).
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:
+ `"timestamp"`: o horário em que a mensagem de log foi gerada.
+ `"level"`: o nível de log atribuído à mensagem.
+ `"message"`: o conteúdo da mensagem de log.
+ `"requestId"`: o ID de solicitação exclusivo para invocar a função.
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](#ruby-logging-output), 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.
**Example Exemplo de código de registro em log do Ruby**
```
require 'logger'
def lambda_handler(event:, context:)
logger = Logger.new($stdout)
logger.info("Inside the handler function")
end
```
**Example Exemplo de registro em log JSON**
```
{
"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.
**Example Exemplo de código de registro em log do Ruby**
```
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
```
**Example Exemplo de registro em log JSON**
```
{
"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.
**Example Exemplo de código de registro em log do Ruby**
```
require 'logger'
def lambda_handler(event:, context:)
logger = Logger.new($stdout)
begin
raise "exception"
rescue => e
logger.error(e)
end
end
```
**Example Exemplo de registro em log JSON**
```
{
"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](monitoring-cloudwatchlogs-log-level.md).
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:
+ Crie saídas de log usando a biblioteca `Logger` padrão do Ruby e configure a função para usar logs em formato JSON. Dessa forma, o AWS Lambda filtra as saídas de log usando o par de valores-chave `"level"` no objeto JSON descrito em [Usar logs JSON estruturados com Ruby](#ruby-logging-json). Para saber como configurar o formato de log da função, consulte [Configurar controles avançados de registro em log para funções do Lambda](monitoring-logs.md#monitoring-cloudwatchlogs-advanced).
+ Use outro método ou biblioteca de logs para criar logs JSON estruturados no código, de modo que incluam um par de valores-chave de `"level"` para definir o nível da saída de log.
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](https://www.ietf.org/rfc/rfc3339.txt) 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.
**Para visualizar logs no console do CloudWatch**
1. No console do Amazon CloudWatch, abra a [página Log groups](https://console.aws.amazon.com/cloudwatch/home?#logs:) (Grupos de log).
1. Escolha o grupo de logs de sua função (**/aws/lambda/{{nome-de-sua-função}}**).
1. Escolha um stream de logs.
Cada fluxo de log corresponde a uma [instância da sua função](lambda-runtime-environment.md). 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
É possível usar a [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 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.
**Example recuperar um ID de log**
O exemplo a seguir mostra como recuperar um *ID de log* do campo `LogResult` para uma função chamada `my-function`.
```
aws lambda invoke --function-name my-function out --log-type Tail
```
A seguinte saída deverá ser mostrada:
```
{
"StatusCode": 200,
"LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}
```
**Example decodificar os logs**
No mesmo prompt de comando, use o utilitário `base64` para decodificar os logs. O exemplo a seguir mostra como recuperar logs codificados em base64 de `my-function`.
```
aws lambda invoke --function-name my-function out --log-type Tail \
--query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode
```
A opção **cli-binary-format** será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute `aws configure set cli-binary-format raw-in-base64-out`. Para obter mais informações, consulte [A AWS CLI comporta opções de linha de comando globais](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) no *Guia do usuário da AWS Command Line Interface versão 2*.
A seguinte saída deverá ser mostrada:
```
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
```
O utilitário `base64` está disponível no Linux, macOS e [Ubuntu no Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Os usuários do macOS precisam usar `base64 -D`.
**Example get-logs.sh script**
No mesmo prompt de comando, use o script a seguir para fazer download dos últimos cinco eventos de log. O script usa `sed` para remover as aspas do arquivo de saída e fica inativo por 15 segundos para que os logs tenham tempo de ficar disponíveis. A saída inclui a resposta do Lambda, e a saída do comando `get-log-events`.
Copie o conteúdo do exemplo de código a seguir e salve no diretório de seu projeto do Lambda como `get-logs.sh`.
A opção **cli-binary-format** será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute `aws configure set cli-binary-format raw-in-base64-out`. Para obter mais informações, consulte [A AWS CLI comporta opções de linha de comando globais](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) no *Guia do usuário da AWS Command Line Interface versão 2*.
```
#!/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
```
**Example macOS e Linux (somente)**
No mesmo prompt de comando, os usuários do macOS e do Linux podem precisar executar o comando a seguir para garantir que o script seja executável.
```
chmod -R 755 get-logs.sh
```
**Example recuperar os últimos cinco eventos de log**
No mesmo prompt de comando, execute o script a seguir para obter os últimos cinco eventos de log.
```
./get-logs.sh
```
A seguinte saída deverá ser mostrada:
```
{
"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 ou[configurar um período de retenção](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#SettingLogRetention)após o qual os logs são excluídos automaticamente.
## Trabalhar com a biblioteca de registro em log do Ruby
A [biblioteca do logger](https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/index.html) 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
```