Verwendung der Lambda-Erweiterungs-API zur Erstellung von Erweiterungen

Autoren von Lambda Event Function verwenden Erweiterungen, um Lambda in ihre bevorzugten Tools für Überwachung, Observability, Sicherheit und Governance zu integrieren. Autoren von Event Function können Erweiterungen von AWS, AWS Partnern und Open-Source-Projekten verwenden. Weitere Informationen zur Verwendung von Erweiterungen finden Sie unter Einführung in AWS Lambda Erweiterungen im AWS Compute-Blog. In diesem Abschnitt wird beschrieben, wie Sie die Lambda-Erweiterungs-API, den Lebenszyklus der Lambda-Ausführungsumgebung und die Lambda-Erweiterungs-API-Referenz verwenden.

Als Erweiterungsautor können Sie die Lambda-Erweiterungs-API verwenden, um sich tief in die Lambda-Ausführungsumgebung zu integrieren. Ihre Erweiterung kann sich für Ereignisse im Lebenszyklus der Event-Funktion und der Ausführungsumgebung registrieren. Als Reaktion auf diese Ereignisse können Sie neue Prozesse starten, Logik ausführen und alle Phasen des Lambda-Lebenszyklus steuern und an ihnen teilnehmen: Initialisierung, Aufruf und Herunterfahren. Darüber hinaus können Sie die Laufzeitprotokoll-API verwenden, um einen Stream von Protokollen zu erhalten.

Eine Erweiterung wird als unabhängiger Prozess in der Ausführungsumgebung ausgeführt und kann auch nach der vollständigen Verarbeitung des Aufrufs der Ereignisfunktion weiter ausgeführt werden. Da Erweiterungen als Prozesse ausgeführt werden, können Sie sie in einer anderen Sprache als die Ereignisfunktion schreiben. Es wird empfohlen, Erweiterungen mit einer kompilierten Sprache zu implementieren.

In diesem Fall handelt es sich bei der Erweiterung um eine eigenständige Binärdatei, die mit unterstützten Laufzeiten kompatibel ist. Alle Laufzeiten der Lambda-Event-Funktion unterstützen Erweiterungen. Wenn Sie eine nicht kompilierte Sprache verwenden, stellen Sie sicher, dass Sie eine kompatible Laufzeit in die Erweiterung aufnehmen.

Lambda unterstützt auch interne Erweiterungen. Eine interne Erweiterung wird als separater Thread im Laufzeitprozess ausgeführt. Die Laufzeit startet und stoppt die interne Erweiterung. Eine alternative Möglichkeit zur Integration in die Lambda-Umgebung ist die Verwendung sprachspezifischer Umgebungsvariablen und Wrapper-Skripte. Sie können diese nutzen, um die Laufzeitumgebung zu konfigurieren und das Startup-Verhalten des Laufzeitprozesses zu verändern.

Sie können einer Ereignisfunktion auf zwei Arten Erweiterungen hinzufügen. Für eine Ereignisfunktion, die als ZIP-Dateiarchiv bereitgestellt wird, stellen Sie Ihre Erweiterung als Ebene bereit. Für eine als Container-Image definierte Event-Funktion fügen Sie die Erweiterungen zu Ihrem Container-Image hinzu.

Lebenszyklus der Lambda-Ausführungsumgebung

Der Lebenszyklus der Ausführungsumgebung umfasst die folgenden Phasen:

Jede Phase beginnt mit einem Ereignis von Lambda zur Laufzeit und zu allen registrierten Erweiterungen. Die Laufzeit und jede Erweiterung zeigen den Abschluss durch Senden einer Next-API-Anfrage an. Lambda friert die Ausführungsumgebung ein, wenn jeder Prozess abgeschlossen ist und keine ausstehenden Ereignisse vorhanden sind.

Init-Phase

Während dieser Extension init-Phase muss sich jede Erweiterung bei Lambda registrieren, um Ereignisse zu empfangen. Lambda verwendet den vollständigen Dateinamen der Erweiterung, um zu überprüfen, ob die Erweiterung die Bootstrap-Sequenz abgeschlossen hat. Daher muss jeder Register-API-Aufruf den Lambda-Extension-Name-Header mit dem vollständigen Dateinamen der Erweiterung enthalten.

Sie können bis zu 10 Erweiterungen für eine Event-Funktion registrieren. Dieses Limit wird durch den Register-API-Aufruf erzwungen.

Nachdem jede Erweiterung registriert ist, startet Lambda die Runtime init-Phase. Der Laufzeitprozess ruft functionInit auf, um die Function init-Phase zu starten.

Die Init-Phase wird nach der Laufzeit abgeschlossen und jede registrierte Erweiterung zeigt den Abschluss durch Senden einer Next-API-Anforderung an.

Invoke-Phase

Wenn eine Lambda-Ereignisfunktion als Antwort auf eine Next API-Anfrage aufgerufen wird, sendet Lambda ein Invoke Ereignis an die Laufzeit und an jede Erweiterung, die für das Ereignis registriert ist. Invoke

Während des Aufrufs werden externe Erweiterungen parallel zur Event-Funktion ausgeführt. Sie laufen auch weiter, nachdem die Event-Funktion abgeschlossen ist. Sie können damit Diagnoseinformationen erfassen oder Protokolle, Messwerte und Traces an einen Ort Ihrer Wahl senden.

Nachdem Lambda die Antwort der Event-Funktion von der Laufzeit erhalten hat, gibt es die Antwort an den Client zurück, auch wenn Erweiterungen noch laufen.

Die Invoke-Phase endet nach der Laufzeit und alle Erweiterungen signalisieren durch Senden einer Next-API-Anforderung, dass sie ausgeführt wurden.

Event-Payload: Das an die Runtime (und die Lambda-Event-Funktion) gesendete Ereignis trägt die gesamte Anfrage, Header (z. B.RequestId) und Nutzdaten. Das an jede Erweiterung gesendete Ereignis enthält Metadaten, die den Ereignisinhalt beschreiben. Dieses Lebenszyklusereignis umfasst den Typ des Ereignisses, den Zeitpunkt, zu dem die Event-Funktion das Timeout (deadlineMs) überschreitet ()requestId, den Amazon-Ressourcennamen (ARN) der aufgerufenen Event-Funktion und die Tracing-Header.

Erweiterungen, die auf den Ereignistext der Event-Funktion zugreifen möchten, können ein SDK zur Laufzeit verwenden, das mit der Erweiterung kommuniziert. Entwickler von Ereignisfunktionen verwenden das SDK zur Laufzeit, um die Nutzdaten an die Erweiterung zu senden, wenn die Ereignisfunktion aufgerufen wird.

Hier ist ein Beispiel für eine Nutzlast:

{
    "eventType": "INVOKE",
    "deadlineMs": 676051,
    "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
    "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",
    "tracing": {
        "type": "X-Amzn-Trace-Id",
        "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
    }
 }          

Zeitlimit: Die Timeout-Einstellung der Event-Funktion begrenzt die Dauer der gesamten Phase. Invoke Wenn Sie beispielsweise das Timeout für die Event-Funktion auf 360 Sekunden festlegen, müssen die Event-Funktion und alle Erweiterungen innerhalb von 360 Sekunden abgeschlossen sein. Beachten Sie, dass es keine unabhängige Post-Invoke-Phase gibt. Die Dauer ist die Gesamtzeit, die Sie benötigen, bis Ihre Laufzeit und alle Aufrufe Ihrer Erweiterungen abgeschlossen sind. Sie wird erst berechnet, wenn die Ausführung der Ereignisfunktion und aller Erweiterungen abgeschlossen ist.

Auswirkungen auf die Leistung und der Mehraufwand für Erweiterungen: Erweiterungen können sich auf die Leistung der Event-Funktion auswirken. Als Autor einer Erweiterung haben Sie die Kontrolle über die Auswirkungen Ihrer Erweiterung auf die Leistung. Wenn Ihre Erweiterung beispielsweise rechenintensive Operationen ausführt, verlängert sich die Dauer der Ereignisfunktion, da sich die Erweiterung und der Code der Ereignisfunktion dieselben CPU-Ressourcen teilen. Wenn Ihre Erweiterung nach Abschluss des Aufrufs der Ereignisfunktion umfangreiche Operationen ausführt, erhöht sich außerdem die Dauer der Ereignisfunktion, da die Invoke Phase so lange andauert, bis alle Erweiterungen signalisieren, dass sie abgeschlossen sind.

Um die Leistungsbeeinträchtigung zu identifizieren, die durch Erweiterungen in der Invoke-Phase verursacht wird, gibt Lambda die PostRuntimeExtensionsDuration-Metrik aus. Diese Metrik misst die kumulative Zeit, die zwischen der Next-Laufzeit-API-Anforderung und der letzten Next-Erweiterungs-API-Anforderung vergeht. Verwenden Sie die MaxMemoryUsed-Metrik, um die Zunahme des verwendeten Speichers zu messen. Weitere Informationen zu Metriken für Event-Funktionen finden Sie unterCloudWatch Metriken mit Lambda verwenden.

Entwickler von Ereignisfunktionen können verschiedene Versionen ihrer Ereignisfunktionen nebeneinander ausführen, um die Auswirkungen einer bestimmten Erweiterung zu verstehen. Wir empfehlen den Autoren von Erweiterungen, den voraussichtlichen Ressourcenverbrauch zu veröffentlichen, um Entwicklern von Event Function die Auswahl einer geeigneten Erweiterung zu erleichtern.

Shutdown-Phase

Wenn Lambda dabei ist, die Laufzeit zu beenden, sendet es ein Shutdown an die Laufzeitumgebung und dann an jede registrierte externe Erweiterung. Erweiterungen können diese Zeit für abschließende Bereinigungsaufgaben verwenden. Das Shutdown-Ereignis wird als Antwort auf eine Next-API-Anforderung gesendet.

Duration Limit (Begrenzung der Dauer): Die maximale Dauer der Shutdown-Phase hängt von der Konfiguration der registrierten Erweiterungen ab:

Wenn die Laufzeit oder eine Erweiterung nicht innerhalb des Limits auf das Shutdown-Ereignis reagiert, beendet Lambda den Prozess mit einem SIGKILL-Signal.

Event Payload (Ereignis-Nutzlast): Das Shutdown-Ereignis enthält den Grund für das Abschalten und die verbleibende Zeit in Millisekunden.

Das shutdownReason beinhaltet die folgenden Werte:

{ 
  "eventType": "SHUTDOWN", 
  "shutdownReason": "reason for shutdown", 
  "deadlineMs": "the time and date that the function times out in Unix time milliseconds" 
}        
      

Berechtigungen und Konfiguration

Erweiterungen werden in derselben Ausführungsumgebung wie die Lambda-Ereignisfunktion ausgeführt. Erweiterungen teilen sich mit der Event-Funktion auch Ressourcen wie CPU, Arbeitsspeicher und /tmp Festplattenspeicher. Darüber hinaus verwenden Erweiterungen dieselbe AWS Identity and Access Management (IAM-) Rolle und denselben Sicherheitskontext wie die Event-Funktion.

Dateisystem- und Netzwerkzugriffsberechtigungen: Erweiterungen werden im selben Dateisystem und Netzwerknamensraum ausgeführt wie die Event Function-Laufzeit. Dies bedeutet, dass Erweiterungen mit dem zugehörigen Betriebssystem kompatibel sein müssen. Wenn für eine Erweiterung zusätzliche Regeln für ausgehenden Netzwerkverkehr erforderlich sind, müssen Sie diese Regeln auf die Konfiguration der Ereignisfunktion anwenden.

Umgebungsvariablen: Erweiterungen können auf die Umgebungsvariablen der Ereignisfunktion zugreifen, mit Ausnahme der folgenden Variablen, die für den Laufzeitprozess spezifisch sind:

Fehlerbehandlung

Initialization failures (Initialisierungsfehler): Wenn eine Erweiterung fehlschlägt, startet Lambda die Ausführungsumgebung neu, um konsistentes Verhalten zu erzwingen und Fail Fast für Erweiterungen zu unterstützen. Für einige Kunden müssen die Erweiterungen auch geschäftskritische Anforderungen wie Protokollierung, Sicherheit, Governance und Telemetrieerfassung erfüllen.

Fehler beim Aufrufen (z. B. zu wenig Arbeitsspeicher, Timeout bei Eventfunktionen): Da Erweiterungen Ressourcen gemeinsam mit der Laufzeit nutzen, wirkt sich dies auf sie aus. Wenn die Laufzeit ausfällt, nehmen alle Erweiterungen und die Laufzeit selbst an der Shutdown-Phase teil. Darüber hinaus wird die Laufzeit neu gestartet — entweder automatisch als Teil des aktuellen Aufrufs oder durch einen Mechanismus zur verzögerten Neuinitialisierung.

Wenn währenddessen ein Fehler auftritt (z. B. ein Timeout für die Event-Funktion oder ein Laufzeitfehler)Invoke, führt der Lambda-Service einen Reset durch. Der Reset verhält sich wie ein Shutdown-Ereignis. Zuerst beendet Lambda die Laufzeit und sendet dann ein Shutdown-Ereignis an jede registrierte externe Erweiterung. Das Ereignis enthält den Grund für das Abschalten. Wenn diese Umgebung für einen neuen Aufruf verwendet wird, werden die Erweiterung und die Laufzeit als Teil des nächsten Aufrufers neu initialisiert.

Eine ausführlichere Erläuterung des vorherigen Diagramms finden Sie unter Fehler während der Aufrufphase.

Erweiterungsprotokolle: Lambda sendet die Protokollausgabe von Erweiterungen an CloudWatch Logs. Lambda generiert auch ein zusätzliches Protokollereignis für jede Erweiterung während Init. Das Protokollereignis zeichnet den Namen und die Registrierungseinstellung (Ereignis, Konfiguration) bei Erfolg oder die Fehlerursache bei einem Fehler auf.

Fehlerbehebung bei Erweiterungen

Erweiterungs-API-Referenz

Die OpenAPI-Spezifikation für die Erweiterungs-API Version 2020-01-01 finden Sie hier: extensions-api.zip

Sie können den Wert des API-Endpunkts aus der AWS_LAMBDA_RUNTIME_API-Umgebungsvariablen abrufen. Um eine Register-Anforderung zu senden, verwenden Sie das Präfix 2020-01-01/ vor jedem API-Pfad. Zum Beispiel:

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register 

Registrieren

Während Extension init müssen sich alle Erweiterungen bei Lambda registrieren, um Ereignisse zu empfangen. Lambda verwendet den vollständigen Dateinamen der Erweiterung, um zu überprüfen, ob die Erweiterung die Bootstrap-Sequenz abgeschlossen hat. Daher muss jeder Register-API-Aufruf den Lambda-Extension-Name-Header mit dem vollständigen Dateinamen der Erweiterung enthalten.

Interne Erweiterungen werden vom Laufzeitprozess gestartet und gestoppt, sodass sie sich nicht für das Shutdown-Ereignis registrieren können.

Pfad – /extension/register

Methode – POST

Anfordern von Headern

{
    'events': [ 'INVOKE', 'SHUTDOWN']
}             

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler"
}               

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler",
    "accountId": "123456789012"
}

Next

Erweiterungen senden eine Next-API-Anforderung für den Empfang des nächsten Ereignisses, bei dem es sich um ein Invoke-Ereignis oder ein Shutdown-Ereignis handeln kann. Der Antworttext enthält die Nutzlast, bei der es sich um ein JSON-Dokument handelt, das Ereignisdaten enthält.

Die Erweiterung sendet eine Next-API-Anforderung, um zu signalisieren, dass sie bereit ist, neue Ereignisse zu empfangen. Das ist ein blockierender Aufruf.

Legen Sie für den GET-Aufruf kein Timeout fest, da die Erweiterung für einen bestimmten Zeitraum angehalten werden kann, bis ein Ereignis zurückgegeben werden soll.

Pfad – /extension/event/next

Methode – GET

Init-Fehler

Die Erweiterung verwendet diese Methode, um einen Initialisierungsfehler an Lambda zu melden. Rufen Sie sie auf, wenn die Erweiterung nach der Registrierung nicht initialisiert werden kann. Nachdem der Fehler von Lambda empfangen wurde, sind keine weiteren API-Aufrufe erfolgreich. Die Erweiterung sollte beendet werden, nachdem sie die Antwort von Lambda erhalten hat.

Pfad – /extension/init/error

Methode – POST

Dieses Feld ist ein JSON-Objekt mit der folgenden Struktur:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Beachten Sie, dass Lambda jeden Wert für errorType akzeptiert.

Das folgende Beispiel zeigt eine Lambda-Funktionsfehlermeldung, in der die Funktion die im Aufruf bereitgestellten Ereignisdaten nicht analysieren konnte.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

Exit-Fehler

Die Erweiterung verwendet diese Methode, um Lambda vor dem Beenden einen Fehler zu melden. Rufen Sie sie auf, wenn ein unerwarteter Fehler auftritt. Nachdem der Fehler von Lambda empfangen wurde, sind keine weiteren API-Aufrufe erfolgreich. Die Erweiterung sollte beendet werden, nachdem sie die Antwort von Lambda erhalten hat.

Pfad – /extension/exit/error

Methode – POST

Dieses Feld ist ein JSON-Objekt mit der folgenden Struktur:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Beachten Sie, dass Lambda jeden Wert für errorType akzeptiert.

Das folgende Beispiel zeigt eine Lambda-Funktionsfehlermeldung, in der die Funktion die im Aufruf bereitgestellten Ereignisdaten nicht analysieren konnte.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}