Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# 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.](monitoring-cloudwatchlogs.md).
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
**Topics**
+ [Creazione di una funzione che restituisce i registri](#ruby-logging-output)
+ [Utilizzo dei controlli di registrazione avanzati Lambda con Ruby](#ruby-logging-advanced)
+ [Visualizzazione dei log nella console Lambda](#ruby-logging-console)
+ [Visualizzazione dei log nella console CloudWatch](#ruby-logging-cwconsole)
+ [Visualizzazione dei log utilizzando AWS Command Line Interface ()AWS CLI](#ruby-logging-cli)
+ [Eliminazione dei log](#ruby-logging-delete)
+ [Utilizzo della libreria dei logger Ruby](#ruby-logging-lib)
## 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.
**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 dei 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
```
Il runtime di Ruby registra `START`, `END` e `REPORT` per ogni chiamata. La riga del report fornisce i seguenti dettagli.
**Campi dati della riga REPORT**
+ **RequestId**— L'ID univoco della richiesta per la chiamata.
+ **Durata** – La quantità di tempo che il metodo del gestore della funzione impiega durante l'elaborazione dell'evento.
+ **Durata fatturata** – La quantità di tempo fatturata per la chiamata.
+ **Dimensioni memoria** – La quantità di memoria allocata per la funzione.
+ **Quantità max utilizzata** – La quantità di memoria utilizzata dalla funzione. Quando le invocazioni condividono un ambiente di esecuzione, Lambda riporta la memoria massima utilizzata in tutte le invocazioni. Questo comportamento potrebbe comportare un valore riportato superiore al previsto.
+ **Durata Init** – Per la prima richiesta servita, la quantità di tempo impiegato dal runtime per caricare la funzione ed eseguire il codice al di fuori del metodo del gestore.
+ **XRAY TraceId** [— Per le richieste tracciate, l'ID di traccia.AWS X-Ray](services-xray.md)
+ **SegmentId**— Per le richieste tracciate, l'ID del X-Ray segmento.
+ **Campionato** – Per le richieste tracciate, il risultato del campionamento.
Per ottenere log più dettagliati, utilizza la [Utilizzo della libreria dei logger Ruby](#ruby-logging-lib).
## 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:
+ **Formato di registro**: seleziona tra testo semplice e formato JSON strutturato per i registri della funzione
+ **Livello di log**: per i log in formato JSON, scegli il livello di dettaglio dei log che Lambda invia ad CloudWatch Amazon, come ERROR, DEBUG o INFO
+ Gruppo di **log: scegli il gruppo** di log a cui la CloudWatch funzione invia i log
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](monitoring-logs.md#monitoring-cloudwatchlogs-advanced).
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:
+ `"timestamp"`: l'ora in cui è stato generato il messaggio di log
+ `"level"`: il livello di log assegnato al messaggio
+ `"message"`: il contenuto del messaggio di log
+ `"requestId"`: l'ID di richiesta univoco dell'invocazione alla funzione
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 in[Creazione di una funzione che restituisce i registri](#ruby-logging-output), 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.
**Example Esempio di codice di registrazione Ruby**
```
require 'logger'
def lambda_handler(event:, context:)
logger = Logger.new($stdout)
logger.info("Inside the handler function")
end
```
**Example Esempio di record di registro JSON**
```
{
"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.
**Example Esempio di codice di registrazione 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 Esempio di record di registro JSON**
```
{
"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.error`eccezione viene assegnato il livello di registro ERROR.
**Example Esempio di codice di registrazione Ruby**
```
require 'logger'
def lambda_handler(event:, context:)
logger = Logger.new($stdout)
begin
raise "exception"
rescue => e
logger.error(e)
end
end
```
**Example Esempio di record di registro 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"
}
```
### 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](monitoring-cloudwatchlogs-log-level.md).
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:
+ Crea output di registro utilizzando la `Logger` libreria Ruby standard e configura la tua funzione per utilizzare la formattazione dei log JSON. AWS Lambda quindi filtra gli output di log utilizzando la coppia `"level"` chiave-valore nell'oggetto JSON descritto in. [Utilizzo di log JSON strutturati con Ruby](#ruby-logging-json) Per informazioni su come configurare il formato di registro della funzione, consulta. [Configurazione dei controlli di registrazione avanzati per le funzioni Lambda](monitoring-logs.md#monitoring-cloudwatchlogs-advanced)
+ Usa un'altra libreria o metodo di registrazione per creare log strutturati JSON nel codice che includono una coppia di valori `"level"` chiave che definisce il livello dell'output del registro.
Puoi anche utilizzare un'`puts`istruzione per generare un oggetto JSON contenente un identificatore a livello di registro. L'`puts`istruzione 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](https://www.ietf.org/rfc/rfc3339.txt) 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.
**Per visualizzare i log sulla console CloudWatch**
1. Apri la [pagina Registra gruppi](https://console.aws.amazon.com/cloudwatch/home?#logs:) sulla CloudWatch console.
1. Scegli il gruppo di log per la tua funzione (**/aws/lambda/{{your-function-name}}**).
1. Creare un flusso di log.
Ogni flusso di log corrisponde a un'[istanza della funzione](lambda-runtime-environment.md). 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
È possibile utilizzare [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 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.
**Example recuperare un ID di log**
Nell'esempio seguente viene illustrato come recuperare un *ID di log* dal `LogResult` campo per una funzione denominata `my-function`.
```
aws lambda invoke --function-name my-function out --log-type Tail
```
Verrà visualizzato l’output seguente:
```
{
"StatusCode": 200,
"LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}
```
**Example decodificare i log**
Nello stesso prompt dei comandi, utilizzare l'`base64` utilità per decodificare i log. Nell'esempio seguente viene illustrato come recuperare i log codificati in base64 per `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
```
L'**cli-binary-format**opzione è obbligatoria se si utilizza la AWS CLI versione 2. Per rendere questa impostazione come predefinita, esegui `aws configure set cli-binary-format raw-in-base64-out`. Per ulteriori informazioni, consulta la pagina [AWS CLI supported global command line options](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) nella *Guida per l'utente di AWS Command Line Interface versione 2*.
Verrà visualizzato l’output seguente:
```
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
```
L'utilità `base64` è disponibile su Linux, macOS e [Ubuntu su Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Gli utenti macOS potrebbero dover utilizzare `base64 -D`.
**Example Script get-logs.sh**
Nello stesso prompt dei comandi, utilizzare lo script seguente per scaricare gli ultimi cinque eventi di log. Lo script utilizza `sed` per rimuovere le virgolette dal file di output e rimane in sospensione per 15 secondi in attesa che i log diventino disponibili. L'output include la risposta di Lambda e l'output del comando `get-log-events`.
Copiare il contenuto del seguente esempio di codice e salvare nella directory del progetto Lambda come `get-logs.sh`.
L'**cli-binary-format**opzione è obbligatoria se utilizzi la AWS CLI versione 2. Per rendere questa impostazione come predefinita, esegui `aws configure set cli-binary-format raw-in-base64-out`. Per ulteriori informazioni, consulta la pagina [AWS CLI supported global command line options](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) nella *Guida per l'utente di AWS Command Line Interface versione 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 (solo) macOS e Linux**
Nello stesso prompt dei comandi, gli utenti macOS e Linux potrebbero dover eseguire il seguente comando per assicurarsi che lo script sia eseguibile.
```
chmod -R 755 get-logs.sh
```
**Example recuperare gli ultimi cinque eventi di log**
Nello stesso prompt dei comandi, eseguire lo script seguente per ottenere gli ultimi cinque eventi di log.
```
./get-logs.sh
```
Verrà visualizzato l’output seguente:
```
{
"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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#SettingLogRetention) trascorso il quale i log vengono eliminati automaticamente.
## Utilizzo della libreria dei logger Ruby
La [libreria di registrazione](https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/index.html) 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
```