Registrare e monitorare le funzioni Lambda con Python

AWS Lambda monitora automaticamente le funzioni Lambda e invia le voci di log ad Amazon CloudWatch. La funzione Lambda viene fornita con un gruppo di log CloudWatch con un flusso di log per ogni istanza della funzione. L'ambiente di runtime di Lambda invia al flusso di log i dettagli su ogni invocazione e altri output dal codice della funzione. Per ulteriori informazioni sui log CloudWatch, consulta Utilizzo di CloudWatch Logs con Lambda.

Per l'output dei log dal codice della funzione, puoi utilizzare il modulo di logging integrato. Per ottenere voci più dettagliate, puoi utilizzare qualunque libreria di log che scrive in stdout o stderr.

Stampa nel log

Per inviare l'output base ai log, puoi utilizzare un metodo print nella funzione. L'esempio seguente registra i valori del gruppo di log CloudWatch e il flusso, e l'oggetto evento.

Nota che se la tua funzione genera log utilizzando istruzioni print di Python, Lambda può inviare gli output log a File di log CloudWatch solo in formato di testo normale. Per acquisire i log in formato JSON strutturato, è necessario utilizzare una libreria di registrazione supportata. Per ulteriori informazioni, consulta Utilizzo dei controlli di registrazione avanzati di Lambda con Python.

import os
def lambda_handler(event, context):
    print('## ENVIRONMENT VARIABLES')
    print(os.environ['AWS_LAMBDA_LOG_GROUP_NAME'])
    print(os.environ['AWS_LAMBDA_LOG_STREAM_NAME'])
    print('## EVENT')
    print(event)

START RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Version: $LATEST
## ENVIRONMENT VARIABLES
/aws/lambda/my-function
2023/08/31/[$LATEST]3893xmpl7fac4485b47bb75b671a283c
## EVENT
{'key': 'value'}
END RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95
REPORT RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95  Duration: 15.74 ms  Billed Duration: 16 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 Python registra START, END e REPORT per ogni chiamata. La riga REPORT include i seguenti dati:

Utilizzo di una libreria di log

Per registri più dettagliati, utilizza il modulo di log nella libreria standard o qualunque libreria di log di terzi che scrive in stdout o stderr.

Per i runtime Python supportati, puoi scegliere se i log creati utilizzando il modulo logging standard vengono acquisiti in testo normale o JSON. Per ulteriori informazioni, consulta Utilizzo dei controlli di registrazione avanzati di Lambda con Python.

Attualmente, il formato di log predefinito per tutti i runtime di Python è il testo normale. L'esempio seguente mostra come gli output log creati utilizzando il modulo logging standard vengono acquisiti in testo normale in File di log CloudWatch.

import os
import logging
logger = logging.getLogger()
logger.setLevel("INFO")
  
def lambda_handler(event, context):
    logger.info('## ENVIRONMENT VARIABLES')
    logger.info(os.environ['AWS_LAMBDA_LOG_GROUP_NAME'])
    logger.info(os.environ['AWS_LAMBDA_LOG_STREAM_NAME'])
    logger.info('## EVENT')
    logger.info(event)

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]  2023-08-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## ENVIRONMENT VARIABLES
[INFO]  2023-08-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    /aws/lambda/my-function
[INFO]  2023-08-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    2023/01/31/[$LATEST]1bbe51xmplb34a2788dbaa7433b0aa4d
[INFO]  2023-08-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## EVENT
[INFO]  2023-08-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: 3 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 113.51 ms
XRAY TraceId: 1-5e34a66a-474xmpl7c2534a87870b4370   SegmentId: 073cxmpl3e442861 Sampled: true
  

Utilizzo dei controlli di registrazione avanzati di Lambda con Python

Per avere un maggiore controllo sul modo in cui i log delle tue funzioni vengono acquisiti, elaborati e utilizzati, puoi configurare le seguenti opzioni di registrazione per i runtime Python di Lambda supportati:

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 ulteriori informazioni sull'utilizzo delle opzioni di formato e livello di log con le funzioni Lambda in Python, consulta le istruzioni nelle sezioni seguenti.

Utilizzo di log JSON strutturati con Python

Se si seleziona JSON per il formato di log della funzione, Lambda invierà gli output log dalla libreria di registrazione standard di Python a CloudWatch come JSON strutturati. Ogni oggetto di log JSON contiene almeno quattro coppie chiave-valore con le seguenti chiavi:

La libreria logging di Python può anche aggiungere a tale oggetto JSON ulteriori coppie chiave-valore, come "logger".

Gli esempi nelle sezioni seguenti mostrano come gli output log generati utilizzando la libreria logging di Python vengono acquisiti in File di log CloudWatch quando si configura JSON come formato di log della funzione.

Tieni presente che se usi il metodo print per generare output log di base come descritto in Stampa nel log, Lambda acquisirà questi output come testo normale anche se configuri il formato di registrazione della funzione come JSON.

Output log JSON standard che utilizzano la libreria di registrazione di Python

Il frammento di codice e l'output log negli esempi di seguito mostrano come gli output log standard generati utilizzando la libreria logging di Python vengono acquisiti in File di log CloudWatch quando si configura JSON come formato di log della funzione.

import logging  
logger = logging.getLogger()

def lambda_handler(event, context):
    logger.info("Inside the handler function")

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

Registrazione di parametri aggiuntivi in JSON

Quando il formato dei log della funzione è impostato su JSON, è possibile registrare ulteriori parametri con la libreria standard logging di Python utilizzando la parola chiave extra per passare un dizionario Python all'output dei log.

import logging

def lambda_handler(event, context):
    logging.info(
        "extra parameters example", 
        extra={"a":"b", "b": [3]},
    )

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

Registrazione delle eccezioni in JSON

Il seguente frammento di codice mostra come le eccezioni Python vengono acquisite nell'output log della funzione quando si configura JSON come formato di log. Nota che agli output log generati utilizzando logging.exception viene assegnato il livello di log ERROR.

import logging

def lambda_handler(event, context):
    try:
        raise Exception("exception")
    except:
        logging.exception("msg")

{
  "timestamp": "2023-11-02T16:18:57Z",
  "level": "ERROR",
  "message": "msg",
  "logger": "root",
  "stackTrace": [
    "  File \"/var/task/lambda_function.py\", line 15, in lambda_handler\n    raise Exception(\"exception\")\n"
  ],
  "errorType": "Exception",
  "errorMessage": "exception",
  "requestId": "3f9d155c-0f09-46b7-bdf1-e91dab220855",
  "location": "/var/task/lambda_function.py:lambda_handler:17"
}

Log JSON strutturati con altri strumenti di registrazione

Se per generare log JSON strutturati il codice utilizza già un'altra libreria di registrazione, come ad esempio Powertools per AWS Lambda, non è necessario apportare alcuna modifica. AWS Lambda non esegue la doppia codifica dei log già codificati in JSON. Anche se configuri la funzione affinché utilizzi il formato di log JSON, i tuoi output di registrazione vengono visualizzati in CloudWatch nella struttura JSON che definisci.

L'esempio seguente mostra come vengono acquisiti in File di log CloudWatch gli output log generati utilizzando il pacchetto Powertools per AWS Lambda. Il formato di questo output log è lo stesso indipendentemente dal fatto che la configurazione di registrazione della funzione sia impostata su JSON o TEXT. Per ulteriori informazioni sull'utilizzo di Powertools per AWS Lambda, consulta le pagine Utilizzo di Powertools per AWS Lambda (Python) e di AWS SAM per la registrazione strutturata e Utilizzo di Powertools per AWS Lambda (Python) e di AWS CDK per la registrazione strutturata

from aws_lambda_powertools import Logger

logger = Logger()

def lambda_handler(event, context):
    logger.info("Inside the handler function")

{ 
    "level": "INFO", 
    "location": "lambda_handler:7", 
    "message": "Inside the handler function", 
    "timestamp": "2023-10-31 22:38:21,010+0000", 
    "service": "service_undefined", 
    "xray_trace_id": "1-654181dc-65c15d6b0fecbdd1531ecb30" 
}

Utilizzo del filtraggio a livello di log con Python

Configurando il filtraggio a livello di log, puoi scegliere di inviare a File di log CloudWatch solo i log di un determinato livello di registrazione o di livello inferiore. Per informazioni su come configurare il filtraggio a livello di log della funzione, consulta la pagina Filtraggio a livello di log.

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

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.

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 di CloudWatch

È possibile utilizzare la console Amazon CloudWatch per visualizzare i registri per tutti i richiami della funzione Lambda.

Ogni flusso di log corrisponde a un'istanza della funzione. Nuovi flussi di log vengono visualizzati quando aggiorni la funzione Lambda e quando vengono create istanze aggiuntive per gestire più chiamate simultanee. Per trovare i registri per un richiamo specifico, si consiglia di utilizzare la funzione con AWS X-Ray. X-Ray registra i dettagli sulla richiesta e il flusso di log nella traccia.

Visualizzazione dei log con AWS CLI

AWS CLI è uno strumento open source che consente di interagire con i servizi AWS tramite i comandi nella shell a 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 di altri strumenti di registrazione e librerie

Powertools per AWS Lambda (Python) è un toolkit rivolto agli sviluppatori per implementare le best practice serverless e aumentare la velocità di sviluppo. L'utilità di registrazione fornisce un logger ottimizzato per Lambda che include informazioni aggiuntive sul contesto delle funzioni in tutte le funzioni con output strutturato come JSON. Utilizza l'utility per eseguire le seguenti operazioni:

Utilizzo di Powertools per AWS Lambda (Python) e di AWS SAM per la registrazione strutturata

Segui i passaggi riportati sotto per scaricare, creare e implementare un'applicazione Python Hello World di esempio con moduli Powertools per Python integrati utilizzando AWS SAM. Questa applicazione implementa un back-end dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando si invia una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e parametri a CloudWatch utilizzando Embedded Metric Format e invia le tracce a AWS X-Ray. La funzione restituisce un messaggio hello world.

Gestione della conservazione dei log

I gruppi di log non vengono eliminati automaticamente quando si elimina una funzione. Affinché i log non siano archiviati a tempo indeterminato, elimina il gruppo di log o configura un periodo di conservazione trascorso il quale i log vengono eliminati automaticamente da CloudWatch. Per configurare la conservazione dei log, aggiungi quanto segue al tuo modello AWS SAM:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      # Omitting other properties

  LogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
      RetentionInDays: 7

Utilizzo di Powertools per AWS Lambda (Python) e di AWS CDK per la registrazione strutturata

Segui i passaggi riportati sotto per scaricare, creare e implementare un'applicazione Hello World in Python di esempio con i moduli Powertools per AWS Lambda (Python) integrati utilizzando AWS CDK. Questa applicazione implementa un back-end dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando si invia una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e parametri a CloudWatch utilizzando Embedded Metric Format e invia le tracce a AWS X-Ray. La funzione restituisce un messaggio hello world.