C#-Lambda-Funktionen protokollieren und überwachen

AWS Lambda überwacht automatisch Lambda-Funktionen und sendet Protokolleinträge an Amazon CloudWatch. Ihre Lambda-Funktion enthält eine CloudWatch Logs-Log-Gruppe und einen Log-Stream für jede Instanz Ihrer Funktion. Die Lambda-Laufzeitumgebung sendet Details zu den einzelnen Aufrufen an den Protokollstream und leitet Protokolle und andere Ausgaben aus dem Code Ihrer Funktion weiter. Weitere Informationen zu CloudWatch Logs finden Sie unterVerwendung von CloudWatch-Protokollen mit Lambda.

Erstellen einer Funktion, die Protokolle zurückgibt

Um Logs aus Ihrem Funktionscode auszugeben, können Sie das ILambdaLoggerOn-the-Context-Objekt, die Methoden der Console-Klasse oder eine beliebige Logging-Bibliothek verwenden, die in stdout oder schreibtstderr.

Das. NETRuntime protokolliert die REPORT Zeilen STARTEND, und für jeden Aufruf. Die Berichtszeile enthält die folgenden Details.

Verwenden von erweiterten Lambda-Protokollierungssteuerelementen mit. NET

Um Ihnen mehr Kontrolle darüber zu geben, wie die Protokolle Ihrer Funktionen erfasst, verarbeitet und verwendet werden, können Sie die folgenden Protokollierungsoptionen für unterstützt konfigurieren. NETLaufzeiten:

Weitere Informationen zu diesen Protokollierungsoptionen und Anweisungen zur Konfiguration Ihrer Funktion für deren Verwendung finden Sie unter Konfigurieren erweiterter Protokollierungsoptionen für Lambda-Funktionen.

Um die Optionen für das Protokollformat und die Protokollebene mit Ihrem zu verwenden. NET Lambda-Funktionen finden Sie in den Anleitungen in den folgenden Abschnitten.

Verwenden des strukturierten JSON Protokollformats mit. NET

Wenn Sie das Protokollformat Ihrer Funktion auswählenJSON, sendet Lambda die Protokollausgabe ILambdaLoggerals strukturiertJSON. Jedes JSON Protokollobjekt enthält mindestens fünf Schlüssel-Wert-Paare mit den folgenden Schlüsseln:

Die ILambdaLogger-Instanz kann zusätzliche Schlüssel-Wert-Paare hinzufügen, beispielsweise beim Protokollieren von Ausnahmen. Sie können auch Ihre eigenen zusätzlichen Parameter angeben, wie im Abschnitt Vom Kunden bereitgestellte Protokollparameter beschrieben.

Der folgende Beispiel-Logging-Befehl zeigt, wie Sie eine Protokollnachricht mit dem Level INFO schreiben.

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

Sie können auch eine generische Protokollebene verwenden, die die Protokollebene als Argument verwendet, wie im folgenden Beispiel gezeigt.

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

Die Protokollausgabe dieser Beispielcodefragmente würde wie folgt in CloudWatch Logs erfasst:

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

Wenn Sie Ihrer Protokollausgabe keine Ebene zuweisen, weist Lambda ihr automatisch die Ebene INFO zu.

Ausnahmen protokollieren in JSON

Wenn Sie die strukturierte JSON Protokollierung mit verwendenILambdaLogger, können Sie Ausnahmen in Ihrem Code protokollieren, wie im folgenden Beispiel gezeigt.

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

Das von diesem Code ausgegebene Protokollformat wird im folgenden Beispiel gezeigtJSON. Beachten Sie, dass die message Eigenschaft in der mithilfe des im LogWarning Aufruf angegebenen Nachrichtenarguments aufgefüllt JSON wird, während die errorMessage Eigenschaft aus der Message Eigenschaft der Ausnahme selbst stammt.

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

Wenn das Protokollierungsformat Ihrer Funktion auf gesetzt istJSON, gibt Lambda auch Protokollnachrichten im JSON -Format aus, wenn Ihr Code eine nicht abgefangene Ausnahme auslöst. Der folgende Beispielcodeausschnitt und die Protokollnachricht zeigen, wie nicht abgefangene Ausnahmen protokolliert werden.

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

Vom Kunden bereitgestellte Protokollparameter

Mit JSON -formatierten Protokollnachrichten können Sie zusätzliche Protokollparameter angeben und diese in das Protokoll aufnehmen. message Der folgende Codeausschnitt zeigt einen Befehl zum Hinzufügen von zwei vom Benutzer angegebenen Parametern mit der Bezeichnung retryAttempt und uri. Im Beispiel stammt der Wert dieser Parameter aus den Argumenten retryAttempt und uriDestination, die an den Protokollierungsbefehl übergeben wurden.

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

Die von diesem Befehl ausgegebene Protokollnachricht wird im folgenden Beispiel gezeigtJSON.

{
    "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);

Beachten Sie, dass Lambda, wenn Sie zusätzliche Protokollierungsparameter angeben, diese als Eigenschaften der obersten Ebene im JSON Protokolldatensatz erfasst. Dieser Ansatz unterscheidet sich von einigen gängigen. NETLogging-Bibliotheken wieSerilog, die zusätzliche Parameter in einem separaten untergeordneten Objekt erfassen.

Wenn das Argument, das Sie für einen zusätzlichen Parameter angeben, ein komplexes Objekt ist, verwendet Lambda standardmäßig die ToString()-Methode, um den Wert bereitzustellen. Um anzugeben, dass ein Argument JSON serialisiert werden soll, verwenden Sie das @ Präfix, wie im folgenden Codeausschnitt gezeigt. In diesem Beispiel ist User ein Objekt mit den Eigenschaften FirstName und LastName.

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

Die von diesem Befehl ausgegebene Protokollnachricht wird im folgenden Beispiel JSON gezeigt.

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

Wenn das Argument für einen zusätzlichen Parameter ein Array ist IList oder implementiertIDictionary, fügt Lambda das Argument der JSON Protokollnachricht als Array hinzu, wie im folgenden JSON Beispielprotokolldatensatz gezeigt. In diesem Beispiel nimmt {users} ein IList-Argument entgegen, das Instanzen der User-Eigenschaft mit demselben Format wie im vorherigen Beispiel enthält. Lambda wandelt dieses IList in ein Array um, wobei jeder Wert mit der ToString-Methode erstellt wird.

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

Sie können die Liste auch JSON serialisieren, indem Sie das @ Präfix in Ihrem Logging-Befehl verwenden. Im folgenden JSON Beispielprotokolldatensatz ist die users Eigenschaft JSON serialisiert.

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

Filterung auf Protokollebene mit verwenden. NET

Durch die Konfiguration der Filterung auf Protokollebene können Sie festlegen, dass nur Protokolle mit einer bestimmten Detailebene oder niedriger an CloudWatch Logs gesendet werden. Informationen zur Konfiguration der Filterung auf Protokollebene für Ihre Funktion finden Sie unter Filterung auf Protokollebene.

AWS Lambda Um Ihre Protokollnachrichten nach Protokollebene zu filtern, können Sie entweder JSON formatierte Protokolle verwenden oder die. NETConsoleMethoden zur Ausgabe von Protokollnachrichten. Um JSON formatierte Protokolle zu erstellen, konfigurieren Sie den Protokolltyp Ihrer Funktion auf JSON und verwenden Sie die ILambdaLogger Instanz.

Bei Protokollen JSON im -Format filtert Lambda Ihre Protokollausgaben anhand des Schlüsselwertpaars „level“ in dem unter beschriebenen JSON Objekt. Verwenden des strukturierten JSON Protokollformats mit. NET

Wenn Sie das verwenden. NETConsoleMethoden zum Schreiben von Nachrichten in CloudWatch Logs, Lambda wendet Log-Levels wie folgt auf Ihre Nachrichten an:

Wenn Sie Ihre Funktion so konfigurieren, dass sie Filterung auf Protokollebene verwendet, müssen Sie aus den folgenden Optionen für die Protokollebene auswählen, die Lambda an Logs senden soll. CloudWatch Beachten Sie die Zuordnung der von Lambda verwendeten Protokollebenen zu den von Lambda verwendeten Microsoft-Standardstufen. NETILambdaLogger.

Lambda sendet Protokolle mit der ausgewählten Detailebene und niedriger bis CloudWatch. Wenn Sie beispielsweise eine Protokollebene von konfigurierenWARN, sendet Lambda ProtokolleWARN, die den FATAL StufenERROR, und entsprechen.

Zusätzliche Protokollierungswerkzeuge und Bibliotheken

Elektrowerkzeuge für AWS Lambda (. NET) ist ein Entwickler-Toolkit zur Implementierung von Best Practices für Serverless und zur Steigerung der Entwicklergeschwindigkeit. Das Logging-Hilfsprogramm bietet einen Lambda-optimierten Logger, der zusätzliche Informationen zum Funktionskontext all Ihrer Funktionen enthält, wobei die Ausgabe wie JSON folgt strukturiert ist. Mit diesem Serviceprogramm können Sie Folgendes tun:

Verwenden von Powertools für (. AWS Lambda NET) und AWS SAM für strukturiertes Logging

Gehen Sie wie folgt vor, um eine Hello World C#-Beispielanwendung mit integrierten Powertools für AWS Lambda (herunterzuladen, zu erstellen und bereitzustellen. NET) Module, die das verwenden. AWS SAM Diese Anwendung implementiert ein grundlegendes API Backend und verwendet Powertools für die Ausgabe von Protokollen, Metriken und Traces. Es besteht aus einem Amazon API Gateway-Endpunkt und einer Lambda-Funktion. Wenn Sie eine GET Anfrage an den API Gateway-Endpunkt senden, ruft die Lambda-Funktion Logs und Metriken im Embedded Metric Format auf CloudWatch, sendet sie an und sendet Traces an. AWS X-Ray Die Funktion gibt eine hello world-Nachricht zurück.

Verwalten der Protokollaufbewahrung

Wenn Sie eine Funktion löschen, werden Protokollgruppen nicht automatisch gelöscht. Um zu vermeiden, dass Protokolle auf unbestimmte Zeit gespeichert werden, löschen Sie die Protokollgruppe oder konfigurieren Sie eine Aufbewahrungsfrist, nach deren Ablauf die Protokolle CloudWatch automatisch gelöscht werden. Um die Aufbewahrung von Protokollen einzurichten, fügen Sie Ihrer AWS SAM Vorlage Folgendes hinzu:

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

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

Anzeigen von Protokollen in der Lambda-Konsole

Sie können die Lambda-Konsole verwenden, um die Protokollausgabe nach dem Aufrufen einer Lambda-Funktion anzuzeigen.

Wenn Ihr Code über den eingebetteten Code-Editor getestet werden kann, finden Sie Protokolle in den Ausführungsergebnissen. Wenn Sie das Feature Konsolentest verwenden, um eine Funktion aufzurufen, finden Sie die Protokollausgabe im Abschnitt Details.

Protokolle in der CloudWatch Konsole anzeigen

Sie können die CloudWatch Amazon-Konsole verwenden, um Protokolle für alle Lambda-Funktionsaufrufe anzuzeigen.

Jeder Protokoll-Stream entspricht einer Instance Ihrer Funktion. Ein Protokollstream wird angezeigt, wenn Sie Ihre Lambda-Funktion aktualisieren, und wenn zusätzliche Instances zum Umgang mit mehreren gleichzeitigen Aufrufen erstellt werden. Um Logs für einen bestimmten Aufruf zu finden, empfehlen wir, Ihre Funktion mit zu instrumentieren. AWS X-Ray X-Ray erfasst Details zu der Anforderung und dem Protokollstream in der Trace.

Logs mit dem Befehl () anzeigen AWS Command Line InterfaceAWS CLI

Das AWS CLI ist ein Open-Source-Tool, mit dem Sie mithilfe von Befehlen in Ihrer Befehlszeilen-Shell mit AWS Diensten interagieren können. Zur Durchführung der Schritte in diesem Abschnitt benötigen Sie AWS CLI Version 2.

Sie können die AWS CLI verwenden, um Protokolle für einen Aufruf mit der --log-type-Befehlsoption abzurufen. Die Antwort enthält das Feld LogResult, das bis zu 4 KB base64-verschlüsselte Protokolle aus dem Aufruf enthält.

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

Löschen von Protokollen

Wenn Sie eine Funktion löschen, werden Protokollgruppen nicht automatisch gelöscht. Um das unbegrenzte Speichern von Protokollen zu vermeiden, löschen Sie die Protokollgruppe oder konfigurieren Sie eine Aufbewahrungszeitraum nach dem Protokolle automatisch gelöscht werden.