Java-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 unter CloudWatch Logs mit Lambda verwenden.

Um Protokolle aus Ihrem Funktionscode auszugeben, können Sie Methoden von java.lang.System oder jedes Protokollierungsmodul verwenden, das nach stdout oder stderr schreibt.

Erstellen einer Funktion, die Protokolle zurückgibt

Um Protokolle aus dem Code Ihrer Funktion auszugeben, können Sie Methoden für java.lang.System verwenden oder ein beliebiges Protokollierungsmodul, das in stdout oder stderr schreibt. Die aws-lambda-java-coreBibliothek stellt eine Logger-Klasse mit dem Namen bereit, auf LambdaLogger die Sie vom Kontextobjekt aus zugreifen können. Die Logger-Klasse unterstützt mehrzeilige Protokolle.

Im folgenden Beispiel wird der LambdaLogger-Logger verwendet, der vom Kontextobjekt bereitgestellt wird.

// Handler value: example.Handler
public class Handler implements RequestHandler<Object, String>{
  Gson gson = new GsonBuilder().setPrettyPrinting().create();
  @Override
  public String handleRequest(Object event, Context context)
  {
    LambdaLogger logger = context.getLogger();
    String response = new String("SUCCESS");
    // log execution details
    logger.log("ENVIRONMENT VARIABLES: " + gson.toJson(System.getenv()));
    logger.log("CONTEXT: " + gson.toJson(context));
    // process event
    logger.log("EVENT: " + gson.toJson(event));
    return response;
  }
}

START RequestId: 6bc28136-xmpl-4365-b021-0ce6b2e64ab0 Version: $LATEST
ENVIRONMENT VARIABLES: 
{
    "_HANDLER": "example.Handler",
    "AWS_EXECUTION_ENV": "AWS_Lambda_java8",
    "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": "512",
    ...
}
CONTEXT: 
{
    "memoryLimit": 512,
    "awsRequestId": "6bc28136-xmpl-4365-b021-0ce6b2e64ab0",
    "functionName": "java-console",
    ...
}
EVENT:
{
  "records": [
    {
      "messageId": "19dd0b57-xmpl-4ac1-bd88-01bbb068cb78",
      "receiptHandle": "MessageReceiptHandle",
      "body": "Hello from SQS!",
       ...
    }
  ]
}
END RequestId: 6bc28136-xmpl-4365-b021-0ce6b2e64ab0
REPORT RequestId: 6bc28136-xmpl-4365-b021-0ce6b2e64ab0	Duration: 198.50 ms	Billed Duration: 200 ms	Memory Size: 512 MB	Max Memory Used: 90 MB	Init Duration: 524.75 ms

Die Java-Laufzeit protokolliert die Zeilen START, END und REPORT für jeden Aufruf. Die Berichtszeile enthält die folgenden Details:

Verwenden von Lambda-Optionen für die erweiterte Protokollierung mit Java

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ützte Java-Laufzeiten konfigurieren:

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.

Informationen zur Verwendung der Optionen für das Protokollformat und die Protokollebene mit Ihren Java-Lambda-Funktionen finden Sie in den folgenden Abschnitten.

Verwenden des strukturierten JSON-Protokollformats mit Java

Wenn Sie JSON für das Protokollformat Ihrer Funktion auswählen, sendet Lambda die Protokollausgabe unter Verwendung der LambdaLogger-Klasse als strukturiertes JSON. Jedes JSON-Protokollobjekt enthält mindestens vier Schlüssel-Wert-Paare mit den folgenden Schlüsseln:

Abhängig von der verwendeten Protokollierungsmethode können die im JSON-Format erfassten Protokollausgaben Ihrer Funktion auch zusätzliche Schlüssel-Wert-Paare enthalten.

Um Protokollen, die Sie mit dem LambdaLogger-Logger erstellen, eine Ebene zuzuweisen, müssen Sie in Ihrem Protokollierungsbefehl ein LogLevel-Argument angeben, wie im folgenden Beispiel gezeigt.

LambdaLogger logger = context.getLogger();
logger.log("This is a debug log", LogLevel.DEBUG);

Diese Protokollausgabe mit diesem Beispielcode würde wie folgt in CloudWatch Logs erfasst werden:

{
    "timestamp":"2023-11-01T00:21:51.358Z",
    "level":"DEBUG",
    "message":"This is a debug log",
    "AWSrequestId":"93f25699-2cbf-4976-8f94-336a0aa98c6f"
}

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

Wenn Ihr Code bereits eine andere Protokollierungsbibliothek verwendet, um strukturierte JSON-Protokolle zu erstellen, müssen Sie keine Änderungen vornehmen. Lambda codiert Protokolle, die bereits JSON-codiert sind, nicht doppelt. Selbst wenn Sie Ihre Funktion so konfigurieren, dass sie das JSON-Protokollformat verwendet, erscheinen Ihre Logging-Ausgaben CloudWatch in der von Ihnen definierten JSON-Struktur.

Verwenden der Filterung auf Protokollebene mit Java

AWS Lambda Um Ihre Anwendungsprotokolle nach ihrer Protokollebene zu filtern, muss Ihre Funktion Protokolle im JSON-Format verwenden. Sie können dies auf zwei Arten erreichen:

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

Damit Lambda die Protokolle Ihrer Funktion filtern kann, müssen Sie auch ein "timestamp"-Schlüssel-Wert-Paar in Ihre JSON-Protokollausgabe aufnehmen. Die Uhrzeit muss im gültigen RFC 3339-Zeitstempelformat angegeben werden. Wenn Sie keinen gültigen Zeitstempel angeben, weist Lambda dem Protokoll die Stufe INFO zu und fügt einen Zeitstempel für Sie hinzu.

Lambda sendet Protokolle der ausgewählten Stufe und niedriger bis CloudWatch. Wenn Sie beispielsweise die Protokollebene WARN konfigurieren, sendet Lambda Protokolle, die den Stufen WARN, ERROR und FATAL entsprechen.

Implementierung der erweiterten Protokollierung mit Log4J2 und J SLF4

Um die Protokollausgabe anzupassen, die Protokollierung bei Komponententests zu unterstützen und AWS SDK-Aufrufe zu protokollieren, verwenden Sie Apache Log4j2 mit SLF4 J. Log4j ist eine Logging-Bibliothek für Java-Programme, mit der Sie Protokollebenen konfigurieren und Appender-Bibliotheken verwenden können. SLF4J ist eine Fassadenbibliothek, mit der Sie ändern können, welche Bibliothek Sie verwenden, ohne Ihren Funktionscode zu ändern.

Verwenden Sie den Appender in der aws-lambda-java-log4j2-Bibliothek, um die Anforderungs-ID zu den Protokollen Ihrer Funktion hinzuzufügen.

<Configuration>
  <Appenders>
    <Lambda name="Lambda" format="${env:AWS_LAMBDA_LOG_FORMAT:-TEXT}">
       <LambdaTextFormat>
         <PatternLayout>
             <pattern>%d{yyyy-MM-dd HH:mm:ss} %X{AWSRequestId} %-5p %c{1} - %m%n </pattern>
         </PatternLayout>
       </LambdaTextFormat>
       <LambdaJSONFormat>
         <JsonTemplateLayout eventTemplateUri="classpath:LambdaLayout.json" />
       </LambdaJSONFormat>
     </Lambda>
   </Appenders>
   <Loggers>
     <Root level="${env:AWS_LAMBDA_LOG_LEVEL:-INFO}">
       <AppenderRef ref="Lambda"/>
     </Root>
     <Logger name="software.amazon.awssdk" level="WARN" />
     <Logger name="software.amazon.awssdk.request" level="DEBUG" />
   </Loggers>
 </Configuration>

Sie können entscheiden, wie Ihre Log4j2-Protokolle entweder für Klartext- oder JSON-Ausgaben konfiguriert werden sollen, indem Sie unter den Tags <LambdaTextFormat> und <LambdaJSONFormat> ein Layout angeben.

In diesem Beispiel wird im Textmodus jeder Zeile das Datum, die Uhrzeit, die Anforderungs-ID, die Protokollstufe und der Klassenname vorangestellt. Im JSON-Modus wird das <JsonTemplateLayout> mit einer Konfiguration verwendet, die zusammen mit der aws-lambda-java-log4j2-Bibliothek geliefert wird.

SLF4J ist eine Fassadenbibliothek zum Einloggen in Java-Code. In Ihrem Funktionscode verwenden Sie die SLF4 J Logger Factory, um einen Logger mit Methoden für Log-Levels wie info() und abzurufenwarn(). In Ihrer Build-Konfiguration nehmen Sie die Logging-Bibliothek und den SLF4 J-Adapter in den Klassenpfad auf. Indem Sie die Bibliotheken in der Build-Konfiguration ändern, können Sie den Logger-Typ ändern, ohne Ihren Funktionscode zu ändern. SLF4J ist erforderlich, um Protokolle aus dem SDK for Java zu erfassen.

Im folgenden Beispielcode verwendet die Handler-Klasse SLF4 J, um einen Logger abzurufen.

package example;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.events.S3Event;

import static org.apache.logging.log4j.CloseableThreadContext.put;


public class HandlerS3 implements RequestHandler<S3Event, String>{
    private static final Logger logger = LoggerFactory.getLogger(HandlerS3.class);

    @Override
    public String handleRequest(S3Event event, Context context) {
        for(var record : event.getRecords()) {
            try (var loggingCtx = put("awsRegion", record.getAwsRegion())) {
                loggingCtx.put("eventName", record.getEventName());
                loggingCtx.put("bucket", record.getS3().getBucket().getName());
                loggingCtx.put("key", record.getS3().getObject().getKey());

                logger.info("Handling s3 event");
            }
        }

        return "Ok";
    }
}

Es wird eine ähnliche Protokollausgabe wie die folgende erstellt:

{
    "timestamp": "2023-11-15T16:56:00.815Z",
    "level": "INFO",
    "message": "Handling s3 event",
    "logger": "example.HandlerS3",
    "AWSRequestId": "0bced576-3936-4e5a-9dcd-db9477b77f97",
    "awsRegion": "eu-south-1",
    "bucket": "java-logging-test-input-bucket",
    "eventName": "ObjectCreated:Put",
    "key": "test-folder/"
}

Die Build-Konfiguration verwendet Laufzeitabhängigkeiten vom Lambda-Appender und SLF4 J-Adapter sowie Implementierungsabhängigkeiten von Log4j2.

dependencies {
    ...
    'com.amazonaws:aws-lambda-java-log4j2:[1.6.0,)',
    'com.amazonaws:aws-lambda-java-events:[3.11.3,)',
    'org.apache.logging.log4j:log4j-layout-template-json:[2.17.1,)',
    'org.apache.logging.log4j:log4j-slf4j2-impl:[2.19.0,)',
    ...
}

Wenn Sie Ihren Code vor Ort für Tests ausführen, ist das Kontextobjekt mit dem Lambda-Logger nicht verfügbar, und es gibt keine Anforderungs-ID, die der Lambda-Appender verwenden kann. Beispiele für Testkonfigurationen finden Sie in den Beispielanwendungen im nächsten Abschnitt.

Andere Tools und Bibliotheken für die Protokollierung verwenden

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

Verwendung von Powertools für AWS Lambda (Java) und für strukturiertes Logging AWS SAM

Gehen Sie wie folgt vor, um eine Hello World Java-Beispielanwendung mit integrierten Powertools for AWS Lambda (Java) ~-Modulen herunterzuladen, zu erstellen und bereitzustellen. Verwenden Sie dazu die. AWS SAM Diese Anwendung implementiert ein grundlegendes API-Backend und verwendet Powertools zum Ausgeben 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 auf, sendet sie im Embedded Metric Format an CloudWatch 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 einen Aufbewahrungszeitraum, nach dessen 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.

Beispielprotokolliercode

Das GitHub Repository für dieses Handbuch enthält Beispielanwendungen, die die Verwendung verschiedener Protokollierungskonfigurationen demonstrieren. Jede Beispielanwendung enthält Skripts für die einfache Bereitstellung und Bereinigung, eine AWS SAM Vorlage und unterstützende Ressourcen.

Die java-basic-Beispielanwendung zeigt eine minimale Protokollierungskonfiguration, die Protokollierungstests unterstützt. Der Handler-Code verwendet den LambdaLogger-Logger, der vom Kontextobjekt bereitgestellt wird. Für Tests verwendet die Anwendung eine benutzerdefinierte TestLogger-Klasse, die die LambdaLogger-Schnittstelle mit einem Log4j2-Logger implementiert. Aus Gründen der Kompatibilität mit dem SDK wird SLF4 J als Fassade verwendet. AWS Protokollbibliotheken werden von der Build-Ausgabe ausgeschlossen, um das Bereitstellungspaket klein zu halten.