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 unterLambda-Funktionsprotokolle an CloudWatch Logs senden.

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-core-Bibliothek stellt eine Logger-Klasse mit dem Namen LambdaLogger bereit, auf die Sie vom Kontextobjekt 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: 724 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 Logs Ihrer Funktionen erfasst, verarbeitet und genutzt 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 durch diesen 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 Logausgabe kein Level zuweisen, weist Lambda ihr automatisch das Level INFO zu.

Wenn Ihr Code bereits eine andere Logging-Bibliothek verwendet, um strukturierte JSON-Logs zu erstellen, müssen Sie keine Änderungen vornehmen. Lambda codiert keine Protokolle doppelt, die bereits JSON-kodiert sind. 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 JSON-formatierte Protokolle verwenden. Sie können dies auf zwei Arten erreichen:

Wenn Sie Ihre Funktion so konfigurieren, dass sie die 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 Ebene INFO zu und fügt einen Zeitstempel für Sie hinzu.

Lambda sendet Protokolle der ausgewählten Stufe und niedriger als. 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 SLF4J

Verwenden Sie Apache Log4j2 mit SLF4J, um die Protokollausgabe anzupassen, die Protokollierung bei Komponententests zu unterstützen und AWS SDK-Aufrufe zu protokollieren. Log4j ist eine Logging-Bibliothek für Java-Programme, mit der Sie Log-Levels 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.

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

<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 Protokollieren in Java-Code. In Ihrem Funktionscode verwenden Sie die SLF4J-Logger-Factory, um einen Logger mit Methoden für Protokollstufen wie info() und warn() abzurufen. Bei Ihrer Build-Konfiguration schließen Sie die Protokollierungsbibliothek und den SLF4J-Adapter in den Klassenpfad ein. Durch Ändern der Bibliotheken in der Build-Konfiguration können Sie den Logger-Typ ändern, ohne den Funktionscode zu ändern. SLF4J ist erforderlich, um Protokolle aus SDK for Java zu erfassen.

Im folgenden Beispielcode verwendet die Handler-Klasse SLF4J, 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 nimmt Laufzeitabhängigkeiten auf dem Lambda-Appender sowie SLF4J-Adapter und Implementierungsabhängigkeiten auf Log4j2 an.

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 Erhöhung 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:

Verwenden von Powertools für AWS Lambda (Java) und AWS SAM für strukturiertes Loggen

Folgen Sie den unten stehenden Schritten, um eine Hello World Java-Beispielanwendung mit integrierten Powertools for AWS Lambda (Java) -Modulen mithilfe von herunterzuladen, zu erstellen und bereitzustellen. 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 auf, sendet Protokolle und Metriken im Embedded Metric Format an und sendet CloudWatch 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 im eingebetteten Code-Editor getestet werden kann, finden Sie Protokolle in den Ausführungsergebnissen. Wenn Sie die Konsolentestfunktion verwenden, um eine Funktion aufzurufen, finden Sie die Protokollausgabe im Abschnitt Details.

Protokolle in der Konsole anzeigen CloudWatch

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

Jeder Protokoll-Stream entspricht einer Instance Ihrer Funktion. Ein Log-Stream erscheint, wenn Sie Ihre Lambda-Funktion aktualisieren und wenn zusätzliche Instances erstellt werden, um gleichzeitige Aufrufe zu verarbeiten. Um Logs für einen bestimmten Aufruf zu finden, empfehlen wir, Ihre Funktion mit zu instrumentieren. AWS X-Ray X-Ray zeichnet Details über die Anfrage und den Log-Stream im Trace auf.

Anzeigen von Protokollen mit dem AWS Command Line Interface (AWS 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 eine 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. Es verwendet SLF4J als Fassade für die Kompatibilität mit dem SDK. AWS Protokollbibliotheken werden von der Build-Ausgabe ausgeschlossen, um das Bereitstellungspaket klein zu halten.