Konfiguration erweiterter Protokollierungssteuerungen für Lambda-Funktionen

Um Ihnen mehr Kontrolle darüber zu geben, wie die Protokolle Ihrer Funktionen erfasst, verarbeitet und verwendet werden, bietet Lambda folgende Konfigurationsoptionen für die Protokollierung:

Weitere Informationen zur Konfiguration erweiterter Protokollierungssteuerungen finden Sie in den folgenden Abschnitten:

Konfiguration JSON und Protokollformate im Klartext-Format

Das Erfassen Ihrer Protokollausgaben als JSON Schlüsselwertpaare erleichtert das Suchen und Filtern beim Debuggen Ihrer Funktionen. Mit JSON formatierten Protokollen können Sie Ihren Protokollen auch Tags und Kontextinformationen hinzufügen. Das kann Ihnen bei der automatisierten Analyse großer Mengen von Protokolldaten helfen. Sofern Ihr Entwicklungsworkflow nicht auf vorhandenen Tools basiert, die Lambda-Protokolle im Klartext verarbeiten, empfehlen wir Ihnen, das JSON für Ihr Protokollformat auszuwählen.

Für alle von Lambda verwalteten Laufzeiten können Sie wählen, ob die Systemprotokolle Ihrer Funktion in unstrukturiertem Klartext oder in einem CloudWatch Format an Logs gesendet werden sollen. JSON Systemprotokolle sind die von Lambda generierten Protokolle und werden manchmal auch als Plattformereignisprotokolle bezeichnet.

Wenn Sie für unterstützte Laufzeiten eine der unterstützten integrierten Protokollierungsmethoden verwenden, kann Lambda auch die Anwendungsprotokolle Ihrer Funktion (die Protokolle, die Ihr Funktionscode generiert) in strukturiertem JSON Format ausgeben. Wenn Sie das Protokollformat Ihrer Funktion für diese Laufzeiten konfigurieren, gilt die von Ihnen ausgewählte Konfiguration sowohl für System- als auch für Anwendungsprotokolle.

Wenn Ihre Funktion für unterstützte Laufzeiten eine unterstützte Protokollierungsbibliothek oder -methode verwendet, müssen Sie keine Änderungen an Ihrem vorhandenen Code vornehmen, damit Lambda Logs strukturiert erfassen kann. JSON

Unterstützte Laufzeiten und Protokollierungsmethoden

Lambda unterstützt derzeit die Option, JSON strukturierte Anwendungsprotokolle für die folgenden Laufzeiten auszugeben.

Damit Lambda die Anwendungsprotokolle Ihrer Funktion CloudWatch in strukturiertem JSON Format senden kann, muss Ihre Funktion die folgenden integrierten Protokollierungstools zur Ausgabe von Protokollen verwenden:

Weitere Hinweise zur Verwendung erweiterter Protokollierungsoptionen mit unterstützten Laufzeiten finden Sie unter Protokollieren und Überwachen von Java-Lambda-Funktionen, Lambda-Funktionen von Node.js protokollieren und überwachen und Python-Lambda-Funktionen protokollieren und überwachen.

Für andere verwaltete Lambda-Laufzeiten unterstützt Lambda derzeit nur nativ die Erfassung von Systemprotokollen in strukturiertem Format. JSON Sie können jedoch weiterhin Anwendungsprotokolle in strukturiertem JSON Format zu jeder Laufzeit erfassen, indem Sie Protokollierungstools wie Powertools für AWS Lambda die Ausgabe formatierter Protokollausgaben verwenden. JSON

Standardprotokollformate

Derzeit ist das Standard-Protokollformat für alle Lambda-Laufzeiten das Klartextformat.

Wenn Sie bereits Logging-Bibliotheken wie Powertools verwenden AWS Lambda , um Ihre Funktionsprotokolle im JSON strukturierten Format zu generieren, müssen Sie Ihren Code nicht ändern, wenn Sie die Protokollformatierung auswählenJSON. Lambda codiert keine Protokolle, die bereits JSON codiert sind, doppelt, sodass die Anwendungsprotokolle Ihrer Funktion weiterhin wie zuvor erfasst werden.

JSONFormat für Systemprotokolle

Wenn Sie das Protokollformat Ihrer Funktion als konfigurierenJSON, wird jedes Systemprotokollelement (Plattformereignis) als JSON Objekt erfasst, das Schlüsselwertpaare mit den folgenden Schlüsseln enthält:

Das Format des "record"-Werts hängt von der Art des protokollierten Ereignisses ab. Weitere Informationen finden Sie unter Telemetrieobjekttypen API Event. Weitere Hinweise zu den Protokollebenen, die Systemprotokollereignissen zugewiesen sind, finden Sie unter Zuordnung von Ereignissen auf Systemprotokollebene.

Zum Vergleich zeigen die folgenden beiden Beispiele dieselbe Protokollausgabe sowohl im Klartext- als auch im strukturierten JSON Format. Beachten Sie, dass Systemprotokollereignisse in den meisten Fällen mehr Informationen enthalten, wenn sie im JSON Format ausgegeben werden, als wenn sie im Klartext ausgegeben werden.

2024-03-13 18:56:24.046000 fbe8c1   INIT_START  Runtime Version: python:3.12.v18  Runtime Version ARN: arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0

{
  "time": "2024-03-13T18:56:24.046Z",
  "type": "platform.initStart",
  "record": {
    "initializationType": "on-demand",
    "phase": "init",
    "runtimeVersion": "python:3.12.v18",
    "runtimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0"
  }
}

JSONFormat für Anwendungsprotokolle

Wenn Sie das Protokollformat Ihrer Funktion als konfigurieren, werden AnwendungsprotokollausgabenJSON, die mit unterstützten Protokollierungsbibliotheken und -methoden geschrieben wurden, als JSON Objekt erfasst, das Schlüssel-Wert-Paare mit den folgenden Schlüsseln enthält.

Abhängig von der Laufzeit- und Protokollierungsmethode, die Ihre Funktion verwendet, kann dieses JSON Objekt auch zusätzliche Schlüsselpaare enthalten. Wenn Ihre Funktion beispielsweise in Node.js console Methoden verwendet, um Fehlerobjekte mit mehreren Argumenten zu protokollieren, enthält das JSON Objekt zusätzliche Schlüssel-Wert-Paare mit den Schlüsseln errorMessageerrorType, undstackTrace. Weitere Informationen zu JSON formatierten Protokollen in verschiedenen Lambda-Laufzeiten finden Sie unterPython-Lambda-Funktionen protokollieren und überwachen, undLambda-Funktionen von Node.js protokollieren und überwachen. Protokollieren und Überwachen von Java-Lambda-Funktionen

Zum Vergleich zeigen die folgenden beiden Beispiele dieselbe Protokollausgabe sowohl im Klartext- als auch im strukturierten JSON Format.

2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message

{
    "timestamp":"2024-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"some log message",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}

Festlegen des Protokollformats Ihrer Funktion

Um das Protokollformat für Ihre Funktion zu konfigurieren, können Sie die Lambda-Konsole oder die AWS Command Line Interface (AWS CLI) verwenden. Sie können das Protokollformat einer Funktion auch mit den API Befehlen CreateFunctionund UpdateFunctionConfigurationLambda, der Ressource AWS Serverless Application Model (AWS SAM) AWS: :Serverless: :Function und der Ressource: :Lambda AWS CloudFormation AWS: :Function konfigurieren.

Das Ändern des Protokollformats Ihrer Funktion hat keine Auswirkungen auf bestehende Protokolle, die in Logs gespeichert sind. CloudWatch Nur neue Protokolle verwenden das aktualisierte Format.

Wenn Sie das Protokollformat Ihrer Funktion auf ändern JSON und die Protokollebene nicht festlegen, setzt Lambda die Anwendungsprotokollebene und die Systemprotokollebene Ihrer Funktion automatisch aufINFO. Dies bedeutet, dass Lambda nur Protokollausgaben der Stufe INFO und niedriger an CloudWatch Logs sendet. Weitere Informationen zur Filterung auf Anwendungs- und Systemprotokollebene finden Sie unter Filterung auf Protokollebene

Bei Funktionen von Node.js, die eingebettete Protokolle im metrischen Format (EMF) ausgeben, kann eine Änderung des Protokollformats Ihrer Funktion in dazu JSON führen, CloudWatch dass Ihre Metriken nicht erkannt werden.

Filterung auf Protokollebene

Lambda kann die Protokolle Ihrer Funktion filtern, sodass nur Protokolle mit einer bestimmten Detailebene oder niedriger an CloudWatch Logs gesendet werden. Sie können die Filterung auf Protokollebene separat für die Systemprotokolle Ihrer Funktion (die von Lambda generierten Protokolle) und Anwendungsprotokolle (die von Ihrem Funktionscode generierten Protokolle) konfigurieren.

Für Unterstützte Laufzeiten und Protokollierungsmethoden müssen Sie keine Änderungen an Ihrem Funktionscode vornehmen, damit Lambda die Anwendungsprotokolle Ihrer Funktion filtert.

Für alle anderen Laufzeiten und Protokollierungsmethoden muss Ihr Funktionscode Protokollereignisse in stdout oder stderr als JSON formatierte Objekte ausgeben, die ein Schlüssel-Wert-Paar mit dem Schlüssel enthalten. "level" Lambda interpretiert beispielsweise die folgende Ausgabe stdout als DEBUG Level-Log.

print('{"level": "debug", "msg": "my debug log", "timestamp": "2024-11-02T16:51:31.587199Z"}')

Wenn das "level" Wertfeld ungültig ist oder fehlt, weist Lambda der Protokollausgabe das Level INFO zu. Damit Lambda das Zeitstempelfeld verwenden kann, müssen Sie die Uhrzeit im gültigen RFC3339-Zeitstempelformat angeben. Wenn Sie keinen gültigen Zeitstempel angeben, weist Lambda dem Protokoll die Ebene zu INFO und fügt einen Zeitstempel für Sie hinzu.

Halten Sie sich bei der Benennung des Zeitstempelschlüssels an die Benennungskonventionen der Laufzeit, die Sie verwenden. Lambda unterstützt die meisten gängigen Namenskonventionen, die von den verwalteten Laufzeiten verwendet werden. Zum Beispiel in Funktionen, die den verwenden. NETLaufzeit, Lambda erkennt den Schlüssel"Timestamp".

Bei Anwendungsprotokollen (den durch Ihren Funktionscode generierten Protokollen) können Sie zwischen den folgenden Protokollebenen wählen.

Wenn Sie eine Protokollebene auswählen, sendet Lambda Protokolle auf dieser Ebene und niedriger an CloudWatch Logs. Wenn Sie beispielsweise die Anwendungsprotokollebene einer Funktion auf festlegenWARN, sendet Lambda keine Protokollausgaben auf den DEBUG Ebenen INFO und. Die Standardebene des Anwendungsprotokolls für die Protokollfilterung istINFO.

Wenn Lambda die Anwendungsprotokolle Ihrer Funktion filtert, wird Protokollnachrichten ohne Stufe die Protokollebene zugewiesen. INFO

Für Systemprotokolle (die vom Lambda-Service generierten Protokolle) können Sie zwischen den folgenden Protokollebenen wählen.

Wenn Sie eine Protokollebene auswählen, sendet Lambda Protokolle auf dieser Ebene und niedriger. Wenn Sie beispielsweise die Systemprotokollebene einer Funktion auf setzenINFO, sendet Lambda keine Protokollausgaben auf dieser DEBUG Ebene.

Standardmäßig setzt Lambda die Systemprotokollebene aufINFO. Mit dieser Einstellung sendet "start" und "report" protokolliert Lambda automatisch Nachrichten an CloudWatch. Um mehr oder weniger detaillierte Systemprotokolle zu erhalten, ändern Sie die Protokollebene auf DEBUG oderWARN. Eine Liste der Protokollebenen, denen Lambda verschiedene Systemprotokollereignisse zuordnet, finden Sie unter Zuordnung von Ereignissen auf Systemprotokollebene.

Konfigurieren der Filterung auf Protokollebene

Um die Filterung auf Anwendungs- und Systemprotokollebene für Ihre Funktion zu konfigurieren, können Sie die Lambda-Konsole oder die AWS Command Line Interface () verwenden.AWS CLI Sie können die Protokollebene einer Funktion auch mithilfe der API Befehle CreateFunctionund UpdateFunctionConfigurationLambda, der Ressource AWS Serverless Application Model (AWS SAM) AWS: :Serverless: :Function und der Ressource: :Lambda AWS CloudFormation AWS: :Function konfigurieren.

Beachten Sie, dass, wenn Sie die Protokollebene Ihrer Funktion in Ihrem Code festlegen, diese Einstellung Vorrang vor allen anderen von Ihnen konfigurierten Einstellungen auf Protokollebene hat. Wenn Sie beispielsweise die logging setLevel() Python-Methode verwenden, um die Protokollierungsebene Ihrer Funktion auf festzulegenINFO, hat diese Einstellung Vorrang vor einer EinstellungWARN, die Sie mit der Lambda-Konsole konfigurieren.

Zuordnung von Ereignissen auf Systemprotokollebene

Für von Lambda generierte Protokollereignisse auf Systemebene ist in der folgenden Tabelle die Protokollebene definiert, die jedem Ereignis zugewiesen ist. Weitere Informationen zu den in der Tabelle aufgeführten Ereignissen finden Sie unter Lambda-Telemetrie-Schemareferenz API Event

Filterung auf Anwendungsprotokollebene mit benutzerdefinierten Laufzeiten

Wenn Sie die Filterung auf Anwendungsprotokollebene für Ihre Funktion konfigurieren, legt Lambda hinter den Kulissen die Anwendungsprotokollebene in der Laufzeit mithilfe der Umgebungsvariable AWS_LAMBDA_LOG_LEVEL fest. Lambda legt auch das Protokollformat Ihrer Funktion mithilfe der Umgebungsvariable AWS_LAMBDA_LOG_FORMAT fest. Sie können diese Variablen verwenden, um erweiterte Lambda-Protokollierungsoptionen in eine benutzerdefinierte Laufzeit zu integrieren.

Um Protokollierungseinstellungen für eine Funktion konfigurieren zu können, die eine benutzerdefinierte Laufzeit mit der Lambda-Konsole und Lambda verwendet AWS CLI APIs, konfigurieren Sie Ihre benutzerdefinierte Laufzeit so, dass sie den Wert dieser Umgebungsvariablen überprüft. Anschließend können Sie die Logger Ihrer Laufzeit gemäß dem von Ihnen ausgewählten Protokollformat und den von Ihnen ausgewählten Protokollebenen konfigurieren.

Konfiguration von Protokollgruppen CloudWatch

Standardmäßig wird CloudWatch automatisch eine Protokollgruppe erstellt, die nach Ihrer Funktion benannt ist, wenn sie /aws/lambda/<function name> zum ersten Mal aufgerufen wird. Um Ihre Funktion so zu konfigurieren, dass Protokolle an eine bestehende Protokollgruppe gesendet werden, oder um eine neue Protokollgruppe für Ihre Funktion zu erstellen, können Sie die Lambda-Konsole oder die AWS CLI verwenden. Sie können benutzerdefinierte Protokollgruppen auch mithilfe der API Befehle CreateFunctionund UpdateFunctionConfigurationLambda sowie der Ressource AWS Serverless Application Model (AWS SAM) AWS: :Serverless: :Function konfigurieren.

Sie können mehrere Lambda-Funktionen so konfigurieren, dass sie Protokolle an dieselbe CloudWatch Protokollgruppe senden. Beispielsweise könnten Sie eine einzelne Protokollgruppe verwenden, um Protokolle für alle Lambda-Funktionen zu speichern, aus denen eine bestimmte Anwendung besteht. Wenn Sie eine benutzerdefinierte Protokollgruppe für eine Lambda-Funktion verwenden, enthalten die von Lambda erstellten Protokollstreams den Funktionsnamen und die Funktionsversion. Dadurch wird sichergestellt, dass die Zuordnung zwischen Protokollmeldungen und Funktionen erhalten bleibt, auch wenn Sie dieselbe Protokollgruppe für mehrere Funktionen verwenden.

Das Log-Stream-Benennungsformat für benutzerdefinierte Protokollgruppen folgt dieser Konvention:

YYYY/MM/DD/<function_name>[<function_version>][<execution_environment_GUID>]

Beachten Sie, dass bei der Konfiguration einer benutzerdefinierten Protokollgruppe der Name, den Sie für Ihre Protokollgruppe auswählen, den Benennungsregeln für CloudWatch Protokolle entsprechen muss. Darüber hinaus dürfen benutzerdefinierte Protokollgruppennamen nicht mit der Zeichenfolge aws/ beginnen. Wenn Sie eine benutzerdefinierte Protokollgruppe erstellen, die mit aws/ beginnt, kann Lambda die Protokollgruppe nicht erstellen. Aus diesem Grund werden die Protokolle Ihrer Funktion nicht an gesendet CloudWatch.

Berechtigungen für die Ausführungsrolle

Damit Ihre Funktion Logs an CloudWatch Logs senden kann, muss sie über die Logs: PutLogEvents -Berechtigung verfügen. Wenn Sie die Protokollgruppe Ihrer Funktion mithilfe der Lambda-Konsole konfigurieren und Ihre Funktion diese Berechtigung nicht besitzt, fügt Lambda sie standardmäßig der Ausführungsrolle der Funktion hinzu. Wenn Lambda diese Berechtigung hinzufügt, erteilt es der Funktion die Erlaubnis, Protokolle an jede CloudWatch Logs-Protokollgruppe zu senden.

Um zu verhindern, dass Lambda die Ausführungsrolle der Funktion automatisch aktualisiert, damit Sie diese stattdessen manuell bearbeiten, erweitern Sie Berechtigungen und deaktivieren Sie Erforderliche Berechtigungen hinzufügen.

Wenn Sie die Protokollgruppe Ihrer Funktion mithilfe von konfigurieren AWS CLI, fügt Lambda die logs:PutLogEvents Berechtigung nicht automatisch hinzu. Fügen Sie die Berechtigung zur Ausführungsrolle Ihrer Funktion hinzu, falls noch nicht geschehen. Diese Berechtigung ist in der AWSLambdaBasicExecutionRoleverwalteten Richtlinie enthalten.