Registrare e monitorare le funzioni Lambda con Ruby

AWS Lambda monitora automaticamente le funzioni Lambda per tuo conto e invia i log ad Amazon. CloudWatch La tua funzione Lambda include un gruppo di CloudWatch log Logs e un flusso di log per ogni istanza della tua funzione. L'ambiente del runtime Lambda invia i dettagli su ogni richiamo al flusso di log e inoltra i log e l'output del codice della funzione. Per ulteriori informazioni, consulta Invio dei log delle funzioni Lambda ai CloudWatch log.

Questa pagina descrive come produrre un output di log dal codice della funzione Lambda e accedere ai log utilizzando la AWS Command Line Interface console Lambda o la console. CloudWatch

Creazione di una funzione che restituisce i registri

Per i log di output del codice della funzione, puoi usare le istruzioni puts o qualsiasi libreria di registrazione che scriva in stdout o stderr. L'esempio seguente registra i valori delle variabili di ambiente e l'oggetto evento. Per informazioni sull'oggetto di contesto disponibile per il tuo gestore, consulta. Utilizzo dell'oggetto del contesto Lambda per recuperare le informazioni sulla funzione Ruby

# 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   

Il runtime di Ruby registra START, END e REPORT per ogni chiamata. La riga del report fornisce i seguenti dettagli.

Per ottenere log più dettagliati, utilizza la Utilizzo della libreria dei logger Ruby.

Utilizzo dei controlli di registrazione avanzati Lambda con Ruby

Per darti un maggiore controllo su come i log delle tue funzioni vengono acquisiti, elaborati e consumati, Lambda offre controlli di registrazione avanzati con Ruby. Per i runtime di Ruby 4.0 e versioni successive, puoi configurare le seguenti opzioni di registrazione:

Per ulteriori informazioni su queste opzioni di registrazione e istruzioni su come configurare la funzione per utilizzarle, consulta la pagina Configurazione dei controlli di registrazione avanzati per le funzioni Lambda.

Per saperne di più sull'utilizzo del formato di registro e delle opzioni a livello di registro con le funzioni Ruby Lambda, consulta le linee guida nelle sezioni seguenti.

Utilizzo di log JSON strutturati con Ruby

Se selezioni JSON come formato di registro della tua funzione, Lambda invierà i log generati dalla Logger libreria standard Ruby come JSON strutturato. CloudWatch Ogni oggetto di log JSON contiene almeno quattro coppie chiave-valore con le seguenti chiavi:

La Logger libreria Ruby può anche aggiungere ulteriori coppie chiave-valore, ad esempio a questo oggetto JSON. "logger"

Gli esempi nelle sezioni seguenti mostrano come gli output di log generati utilizzando la Logger libreria Ruby vengono acquisiti in CloudWatch Logs quando si configura il formato di log della funzione come JSON.

Nota che se usi il puts metodo per produrre output di log di base come descritto inCreazione di una funzione che restituisce i registri, Lambda acquisirà questi output come testo semplice, anche se configuri il formato di registrazione della tua funzione come JSON.

Uscite di log JSON standard che utilizzano la libreria Ruby Logger

Il seguente frammento di codice di esempio e l'output del log mostrano come gli output di log standard generati utilizzando la Logger libreria Ruby vengono acquisiti in CloudWatch Logs quando il formato di registro della funzione è impostato su 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"
}

Registrazione di parametri aggiuntivi in JSON

Quando il formato di registro della funzione è impostato su JSON, puoi anche registrare parametri aggiuntivi con la Logger libreria Ruby passando un hash di coppie chiave-valore aggiuntive all'output del 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
    ]
}

Registrazione delle eccezioni in JSON

Il seguente frammento di codice mostra come le eccezioni di Ruby vengono acquisite nell'output del registro della funzione quando configuri il formato di registro come JSON. Nota che agli output di log generati utilizzando logger.error con un'eccezione viene assegnato il livello di 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"
}

Utilizzo del filtro a livello di log con Ruby

Configurando il filtro a livello di log, puoi scegliere di inviare solo i log con un determinato livello di registrazione o inferiore a Logs. CloudWatch Per informazioni su come configurare il filtraggio a livello di log della funzione, consulta la pagina Log-level filtraggio.

Per AWS Lambda filtrare i log delle applicazioni in base al relativo livello di registro, la funzione deve utilizzare i log in formato JSON. Puoi farlo in due modi:

Puoi anche utilizzare un'putsistruzione per generare un oggetto JSON contenente un identificatore a livello di log. L'putsistruzione seguente produce un output in formato JSON in cui il livello di registro è impostato su INFO. AWS Lambda invierà l'oggetto JSON a CloudWatch Logs se il livello di registrazione della funzione è impostato su INFO, DEBUG o TRACE.

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

Per consentire a Lambda di filtrare i log della funzione, è necessario includere anche una coppia chiave-valore "timestamp" nell'output log JSON. L'ora deve essere specificata in un formato di timestamp RFC 3339 valido. Se non fornisci un timestamp valido, Lambda assegnerà al log il livello INFO e aggiungerà un timestamp per tuo conto.

Utilizzo di una libreria di registrazione alternativa

Se è necessario utilizzare una versione personalizzata della logger libreria, è possibile includerla nel pacchetto di distribuzione o in un livello Lambda e impostare la variabile di RUBYLIB ambiente nella directory della libreria. lib Il runtime Lambda caricherà la tua versione anziché quella in bundle.

Se il codice utilizza già un'altra libreria di registrazione per produrre log strutturati JSON, non è necessario apportare alcuna modifica. AWS Lambda non codifica due volte i log già codificati in JSON. Anche se configuri la tua funzione per utilizzare il formato di log JSON, i tuoi output di registrazione vengono visualizzati nella CloudWatch struttura JSON definita.

Visualizzazione dei log nella console Lambda

È possibile utilizzare la console Lambda per visualizzare l'output del log dopo aver richiamato una funzione Lambda.

Se il codice può essere testato dall'editor di codice incorporato, i log sono contenuti nei risultati dell'esecuzione. Quando utilizzi la funzionalità di test della console per richiamare una funzione, trovi l'output del registro nella sezione Dettagli.

Visualizzazione dei log nella console CloudWatch

Puoi utilizzare la CloudWatch console Amazon per visualizzare i log di tutte le chiamate di funzioni Lambda.

Ogni flusso di log corrisponde a un'istanza della funzione. Un flusso di log viene visualizzato quando si aggiorna la funzione Lambda e quando vengono create istanze aggiuntive per gestire chiamate simultanee. Per trovare i log per una chiamata specifica, ti consigliamo di strumentare la tua funzione con. AWS X-Ray X-Ray registra i dettagli sulla richiesta e sul flusso di log nella traccia.

Visualizzazione dei log utilizzando AWS Command Line Interface (AWS CLI)

AWS CLI È uno strumento open source che puoi utilizzare per interagire con i AWS servizi utilizzando i comandi nella shell della riga di comando. Per completare le fasi riportate in questa sezione, è necessario disporre della AWS CLI versione 2.

È possibile utilizzare AWS CLI per recuperare i log per una chiamata utilizzando l'opzione di comando --log-type. La risposta include un campo LogResult che contiene fino a 4 KB di log con codifica base64 del richiamo.

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"
}

Eliminazione dei log

I gruppi di log non vengono eliminati automaticamente quando si elimina una funzione. Per evitare di archiviare i log a tempo indeterminato, eliminare il gruppo di log o configurare un periodo di conservazione trascorso il quale i log vengono eliminati automaticamente.

Utilizzo della libreria dei logger Ruby

La libreria di registrazione Ruby restituisce log semplificati e facilmente leggibili. Utilizza l'utilità di registrazione per generare informazioni dettagliate, messaggi e codici di errore relativi alla tua funzione.

# 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

L'output di logger include il livello del log, il timestamp e l'ID della richiesta.

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