Python-Lambda-Funktionen protokollieren und überwachen

AWS Lambda überwacht automatisch Lambda-Funktionen und sendet Protokolleinträge an Amazon CloudWatch. Ihre Lambda-Funktion besitzt eine CloudWatch-Logs-Protokollgruppe und einen Protokollstream für jede Instance 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 Verwendung von CloudWatch-Protokollen mit Lambda.

Zur Ausgabe von Protokollen aus Ihrem Funktionscode können Sie das integrierte logging-Modul verwenden. Für detailliertere Einträge können Sie jede Protokollierungsbibliothek verwenden, die in stdout oder stderr schreibt.

Ausdrucken in das Protokoll

Um eine grundlegende Ausgabe an die Protokolle zu senden, können Sie in Ihrer Funktion eine print-Methode verwenden. Im folgenden Beispiel werden die Werte der CloudWatch-Logs-Protokollgruppe und des Streams sowie des Ereignisobjekts protokolliert.

Beachten Sie Folgendes: Wenn Ihre Funktion Protokolle mithilfe von Python-print-Anweisungen ausgibt, kann Lambda Protokollausgaben nur im Klartextformat an CloudWatch Logs senden. Um Protokolle in strukturiertem JSON zu erfassen, müssen Sie eine unterstützte Protokollierungsbibliothek verwenden. Weitere Informationen finden Sie unter Verwenden von Lambda-Optionen für die erweiterte Protokollierung mit 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   

Die Python-Laufzeit protokolliert die Zeilen START, END und REPORT für jeden Aufruf. Die REPORT-Zeile enthält die folgenden Daten:

Verwendung einer Protokollierungsbibliothek

Für detailliertere Protokolle verwenden Sie das Modul zur Protokollierung in der Standardbibliothek oder eine beliebige Protokollierungsbibliothek eines Drittanbieters, die in stdout oder stderr schreibt.

Für unterstützte Python-Laufzeiten können Sie wählen, ob mit dem logging-Standardmodul erstellte Protokolle im Klartext oder in JSON erfasst werden. Weitere Informationen hierzu finden Sie unter Verwenden von Lambda-Optionen für die erweiterte Protokollierung mit Python.

Derzeit ist das Standard-Protokollformat für alle Python-Laufzeiten das Klartextformat. Das folgende Beispiel zeigt, wie Protokollausgaben, die mit dem logging-Standardmodul erstellt wurden, in CloudWatch Logs im Klartext erfasst werden.

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)

Die Ausgabe aus logger umfasst die Protokollebene, den Zeitstempel und die Anforderungs-ID.

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
  

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

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 Lambda-Python-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.

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

Verwenden strukturierter JSON-Protokolle mit Python

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

Die logging-Bibliothek von Python kann auch zusätzliche Schlüssel-Wert-Paare wie "logger" zu diesem JSON-Objekt hinzufügen.

Die Beispiele in den folgenden Abschnitten zeigen, wie mit der logging-Python-Bibliothek generierte Protokollausgaben in CloudWatch Logs erfasst werden, wenn Sie das Protokollformat Ihrer Funktion als JSON konfigurieren.

Beachten Sie Folgendes: Wenn Sie die print-Methode verwenden, um grundlegende Protokollausgaben zu erzeugen, wie unter Ausdrucken in das Protokoll beschrieben, erfasst Lambda diese Ausgaben als Klartext, auch wenn Sie das Protokollierungsformat Ihrer Funktion als JSON konfigurieren.

Standard-JSON-Protokollausgaben mithilfe der Python-Protokollierungsbibliothek

Der folgende Beispiel-Codeausschnitt und die Protokollausgaben zeigen, wie mit der logging-Python-Bibliothek generierte Protokollausgaben in CloudWatch Logs erfasst werden, wenn Sie das Protokollformat Ihrer Funktion als JSON konfigurieren.

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

Protokollieren zusätzlicher Parameter in JSON

Wenn das Protokollformat Ihrer Funktion auf JSON eingestellt ist, können Sie auch zusätzliche Parameter mit der standardmäßigen Python logging-Bibliothek protokollieren, indem Sie das Schlüsselwort extra verwenden, um ein Python-Wörterbuch an die Protokollausgabe zu übergeben.

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

Protokollierungsausnahmen in JSON

Der folgende Codeausschnitt zeigt, wie Python-Ausnahmen in der Protokollausgabe Ihrer Funktion erfasst werden, wenn Sie das Protokollformat als JSON konfigurieren. Beachten Sie, dass den mit logging.exception generierten Protokollausgaben die Protokollebene ERROR zugewiesen wird.

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

Strukturierte JSON-Protokolle mit anderen Protokollierungstools

Wenn Ihr Code bereits eine andere Protokollierungsbibliothek wie Powertools for AWS Lambda verwendet, um strukturierte JSON-Protokolle zu erstellen, müssen Sie keine Änderungen vornehmen. AWS Lambda codiert Protokolle, die bereits JSON-codiert sind, nicht doppelt. Selbst wenn Sie Ihre Funktion für die Verwendung des JSON-Protokollformats konfigurieren, werden Ihre Protokollierungsausgaben in CloudWatch in der von Ihnen definierten JSON-Struktur angezeigt.

Das folgende Beispiel zeigt, wie mit dem Powertools for AWS Lambda-Paket generierte Protokollausgaben in CloudWatch Logs erfasst werden. Das Format dieser Protokollausgabe ist dasselbe, unabhängig davon, ob die Protokollierungskonfiguration Ihrer Funktion auf JSON oder TEXT festgelegt ist. Weitere Informationen zur Verwendung von Powertools for AWS Lambda finden Sie unter Verwenden von Powertools für AWS Lambda (Python) und AWS SAM für strukturierte Protokollierung und Verwenden von Powertools für AWS Lambda (Python) und AWS CDK für strukturierte Protokollierung.

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

Verwenden der Filterung auf Protokollebene mit Python

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

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

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.

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.

Anzeigen von Protokollen in der CloudWatch-Konsole

Sie können die Amazon-CloudWatch-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 Protokolle für einen bestimmten Aufruf zu finden, empfehlen wir, Ihre Funktion mit AWS X-Ray zu instrumentieren. X-Ray erfasst Details zu der Anforderung und dem Protokollstream in der Trace.

Anzeigen von Protokollen mit der AWS CLI

Die AWS CLI ist ein Open-Source-Tool, mit dem Sie über Befehle in Ihrer Befehlszeilen-Shell mit den AWS-Services 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.

Andere Tools und Bibliotheken für die Protokollierung verwenden

Powertools für AWS Lambda (Python) ist ein Entwickler-Toolkit zur Implementierung bewährter Methoden für Serverless und zur Steigerung der Entwicklergeschwindigkeit. Das Logger-Serviceprogramm bietet einen für Lambda optimierten Logger, der zusätzliche Informationen über den 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 (Python) und AWS SAM für strukturierte Protokollierung

Führen Sie die nachstehenden Schritte aus, um eine Hello-World-Python-Beispielanwendung mit integrierten -Powertools for Python-Modulen unter Verwendung von AWS SAM bereitzustellen. 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-Anforderung an den API-Gateway-Endpunkt senden, startet die Lambda-Funktion, sendet Protokolle und Metriken 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 das unbegrenzte Speichern von Protokollen zu vermeiden, löschen Sie die Protokollgruppe oder konfigurieren Sie eine Aufbewahrungszeitraum nach dem CloudWatch die Protokolle automatisch löscht. Um die Protokollaufbewahrung 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

Verwenden von Powertools für AWS Lambda (Python) und AWS CDK für strukturierte Protokollierung

Führen Sie die nachstehenden Schritte aus, um eine Hello-World-Beispielanwendung für Python mit integrierten Modulen von Powertools für AWS Lambda (Python) unter Verwendung von AWS CDK bereitzustellen. 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-Anforderung an den API-Gateway-Endpunkt senden, startet die Lambda-Funktion, sendet Protokolle und Metriken im Embedded Metric Format an CloudWatch und sendet Traces an AWS X-Ray. Die Funktion gibt eine Hello-World-Nachricht zurück.