Registrare e monitorare le funzioni Lambda con C#

AWS Lambda monitora automaticamente le funzioni Lambda e invia le voci di registro 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 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 CloudWatch registri, consulta. Utilizzo di CloudWatch Logs con Lambda

Creazione di una funzione che restituisce i registri

Per generare i log dal codice della funzione, potete utilizzare l'oggetto ILambdaLoggeron the context, i metodi della classe Console o qualsiasi libreria di registrazione che scriva su o. stdout stderr

Il. NETruntime registra le REPORT righe STARTEND, e per ogni chiamata. La riga del report fornisce i seguenti dettagli.

Utilizzo dei controlli di registrazione avanzati Lambda con. NET

Per darti un maggiore controllo sul modo in cui i log delle tue funzioni vengono acquisiti, elaborati e utilizzati, puoi configurare le seguenti opzioni di registrazione come supportate. NETtempi di esecuzione:

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 utilizzare le opzioni relative al formato e al livello di registro con i tuoi. NET Funzioni Lambda, consulta la guida nelle sezioni seguenti.

Utilizzo del formato di JSON registro strutturato con. NET

Se si seleziona JSON il formato di registro della funzione, Lambda invierà l'output dei log utilizzando ILambdaLoggercome strutturato. JSON Ogni oggetto di JSON registro contiene almeno cinque coppie di valori chiave con le seguenti chiavi:

L'istanza ILambdaLogger può aggiungere ulteriori coppie chiave-valore, ad esempio durante la registrazione delle eccezioni. È inoltre possibile fornire parametri aggiuntivi personalizzati come descritto nella sezione Parametri di log forniti dal cliente.

Il seguente comando di registrazione di esempio mostra come scrivere un messaggio di log con il livello INFO.

context.Logger.LogInformation("Fetching cart from database");

Inoltre, puoi usare un metodo di log generico che utilizza il livello di log come argomento come mostrato nell'esempio seguente.

context.Logger.Log(LogLevel.Information, "Fetching cart from database");

L'output di registro di questi frammenti di codice di esempio verrebbe acquisito in CloudWatch Logs come segue:

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Fetching cart from database"
}

Se non assegni un livello all'output del log, Lambda lo assegnerà automaticamente. INFO

Registrazione delle eccezioni in JSON

Quando si utilizza JSON la registrazione strutturata conILambdaLogger, è possibile registrare le eccezioni nel codice come illustrato nell'esempio seguente.

try
{
    connection.ExecuteQuery(query);
}
catch(Exception e)
{
    context.Logger.LogWarning(e, "Error executing query");
}

Il formato di registro generato da questo codice è illustrato nell'esempio seguente. JSON Si noti che la message proprietà in JSON viene compilata utilizzando l'argomento message fornito nella LogWarning chiamata, mentre la errorMessage proprietà proviene dalla Message proprietà dell'eccezione stessa.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Warning",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Error executing query",
    "errorType": "System.Data.SqlClient.SqlException",
    "errorMessage": "Connection closed",
    "stackTrace": ["<call exception.StackTrace>"]
}

Se il formato di registrazione della funzione è impostato suJSON, Lambda emette anche messaggi di registro in formato -formattati quando il codice JSON genera un'eccezione non rilevata. Il frammento di codice e il messaggio di log di esempio seguenti mostrano come vengono registrate le eccezioni non rilevate.

throw new ApplicationException("Invalid data");

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Error",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Invalid data",
    "errorType": "System.ApplicationException",
    "errorMessage": "Invalid data",
    "stackTrace": ["<call exception.StackTrace>"]
}

Parametri di log forniti dal cliente

Con i messaggi di registro JSON -formatted, è possibile fornire parametri di registro aggiuntivi e includerli nel registro. message Il seguente esempio di frammento di codice mostra un comando per aggiungere due parametri forniti dall'utente etichettati retryAttempt e uri. Nell'esempio, il valore di questi parametri deriva dagli argomenti retryAttempt e uriDestination passati al comando di registrazione.

context.Logger.LogInformation("Starting retry {retryAttempt} to make GET request to {uri}", retryAttempt, uriDestination);

Il messaggio di registro emesso da questo comando è illustrato nell'esempio JSON seguente.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Starting retry 1 to make GET request to http://example.com/",
    "retryAttempt": 1,
    "uri": "http://example.com/"
}

context.Logger.LogInformation("Starting retry {0} to make GET request to {1}", retryAttempt, uriDestination);

Tieni presente che quando fornisci parametri di registrazione aggiuntivi, Lambda li acquisisce come proprietà di primo livello nel record di registro. JSON Questo approccio è diverso da alcuni dei più diffusi. NETlibrerie di registrazione comeSerilog, che acquisiscono parametri aggiuntivi in un oggetto figlio separato.

Se l'argomento fornito per un parametro aggiuntivo è un oggetto complesso, per impostazione predefinita Lambda utilizza il metodo ToString() per fornire il valore. Per indicare che un argomento deve essere JSON serializzato, utilizzate il @ prefisso come mostrato nel seguente frammento di codice. In questo esempio, User è un oggetto con proprietà FirstName e LastName.

context.Logger.LogInformation("User {@user} logged in", User);

Il messaggio di registro emesso da questo comando è illustrato nell'esempio seguente. JSON

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "User {@user} logged in",
    "user": 
    {
        "FirstName": "John",
        "LastName": "Doe"
    }
}

Se l'argomento per un parametro aggiuntivo è un array o implementa IList oIDictionary, Lambda aggiunge l'argomento al JSON messaggio di registro come matrice, come mostrato nell'JSONesempio seguente di record di registro. In questo esempio, {users} accetta un argomento IList contenente istanze della proprietà User con lo stesso formato dell'esempio precedente. Lambda converte IList in un array, con ogni valore creato utilizzando il metodo ToString.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "{users} have joined the group",
    "users": 
    [
        "Rosalez, Alejandro",
        "Stiles, John"       
    ] 
}

È inoltre possibile JSON serializzare l'elenco utilizzando il @ prefisso nel comando di registrazione. Nel seguente esempio di record di JSON registro, la users proprietà viene serializzata. JSON

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "{@users} have joined the group",
    "users": 
    [
        {
            "FirstName": "Alejandro",
            "LastName": "Rosalez"
        },
        {
            "FirstName": "John",
            "LastName": "Stiles"
        }        
    ] 
}

Utilizzo del filtraggio a livello di registro con. NET

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

Per AWS Lambda filtrare i messaggi di registro in base al livello di registro, è possibile utilizzare registri formattati o utilizzare JSON il. NETConsolemetodi per generare messaggi di registro. Per creare log JSON formattati, configura il tipo di registro della funzione JSON e usa l'ILambdaLoggeristanza.

Con JSON -formatted logs, Lambda filtra gli output dei log utilizzando la coppia chiave-valore «level» nell'oggetto descritto in. JSON Utilizzo del formato di JSON registro strutturato con. NET

Se usi il. NETConsolemetodi per scrivere messaggi CloudWatch nei registri, Lambda applica i livelli di registro ai messaggi come segue:

Quando configuri la funzione per utilizzare il filtraggio a livello di log, devi selezionare una delle seguenti opzioni per il livello di log che Lambda invii a Logs. CloudWatch Nota la mappatura dei livelli di registro utilizzati da Lambda con i livelli Microsoft standard utilizzati da. NETILambdaLogger.

Lambda invia i log del livello di dettaglio selezionato e inferiore a. CloudWatch Ad esempio, se configuri un livello di registro diWARN, Lambda invierà i log corrispondenti ai livelli WARNERROR, e. FATAL

Strumenti e librerie di registrazione aggiuntivi

Powertools per (. AWS Lambda NET) è un toolkit per sviluppatori per implementare le migliori pratiche Serverless e aumentare la velocità degli sviluppatori. L'utilità Logging 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 NET) e AWS SAM per la registrazione strutturata

Segui i passaggi seguenti per scaricare, creare e distribuire un'applicazione Hello World C# di esempio con Powertools integrato per (. AWS Lambda NET) moduli che utilizzano. AWS SAM Questa applicazione implementa un API backend di base e utilizza Powertools per l'emissione di log, metriche e tracce. È costituito da un endpoint Amazon API Gateway e da una funzione Lambda. Quando invii una GET richiesta all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format a e invia tracce a. CloudWatch 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. Per evitare di archiviare i log a tempo indeterminato, elimina il gruppo di log o configura un periodo di conservazione dopo il quale i log CloudWatch vengono eliminati automaticamente. 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

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. 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 log per una chiamata specifica, ti consigliamo di strumentare la tua funzione con. AWS X-Ray X-Ray registra i dettagli sulla richiesta e il flusso di log nella traccia.

Visualizzazione dei log utilizzando () AWS Command Line InterfaceAWS 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.