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 funzione Lambda include un gruppo di log CloudWatch Logs e un flusso di log per ogni istanza della 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 Lambda invia automaticamente i log delle funzioni a CloudWatch Logs..

Questa pagina descrive come produrre un output di registro dal codice della funzione Lambda e accedere ai log utilizzando AWS Command Line Interface la 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.

# 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 sul modo in cui i log delle tue funzioni vengono acquisiti, elaborati e utilizzati, 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 di livello di registro con le funzioni di Ruby Lambda, consulta la guida nelle sezioni seguenti.

Utilizzo di log JSON strutturati con Ruby

Se si seleziona JSON per il formato di registro della funzione, Lambda invierà i log generati dalla libreria Logger CloudWatch standard Ruby a un formato JSON strutturato. 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 registro generati utilizzando la Logger libreria Ruby vengono acquisiti nei CloudWatch registri quando si configura il formato di registro della funzione come JSON.

Nota che se utilizzi 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 funzione come JSON.

Output di log JSON standard che utilizzano la libreria Ruby Logger

Il seguente frammento di codice e l'output di registro 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, è anche possibile registrare parametri aggiuntivi con la Logger libreria Ruby passando un hash di coppie di valori chiave aggiuntive all'output del registro.

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 di registro della funzione quando si configura il formato di registro come JSON. Si noti che agli output di registro generati utilizzando un'logger.erroreccezione viene assegnato il livello di registro 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 filtraggio a livello di registro con Ruby

Configurando il filtraggio a livello di registro, puoi scegliere di inviare solo i log di un certo 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 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 registro. 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 lib libreria. 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 che sono già codificati in JSON. Anche se configuri la tua funzione per utilizzare il formato di registro JSON, i tuoi output di registrazione vengono visualizzati nella struttura JSON che definisci. CloudWatch

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 del codice incorporato, troverai i log nei risultati dell’esecuzione. Quando utilizzi la funzionalità di test della console per richiamare una funzione, troverai l’output del log 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. Viene visualizzato un flusso di log quando aggiorni la funzione Lambda e quando vengono create istanze aggiuntive per gestire le chiamate simultanee. Per trovare i log per una chiamata specifica, consigliamo di strumentare la 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 consente di 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