Verwenden der Lambda-Erweiterungen API zum Erstellen von Erweiterungen

Lambda-Funktionsautoren verwenden Erweiterungen, um Lambda in ihre bevorzugten Tools zur Überwachung, Beobachtbarkeit, Sicherheit und Governance zu integrieren. Funktionsautoren 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-ErweiterungenAPI, den Lebenszyklus der Lambda-Ausführungsumgebung und die Lambda-Erweiterungsreferenz verwenden. API

Als Autor von Erweiterungen können Sie die Lambda-Erweiterungen verwenden, API um sich tief in die Lambda-Ausführungsumgebung zu integrieren. Ihre Erweiterung kann sich für Lebenszyklusereignisse für Funktions- und 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 Runtime Logs verwenden, API um einen Stream von Protokollen zu empfangen.

Eine Erweiterung wird als unabhängiger Prozess in der Ausführungsumgebung ausgeführt und kann weiterhin ausgeführt werden, nachdem der Funktionsaufruf vollständig verarbeitet wurde. Da Erweiterungen als Prozesse ausgeführt werden, können Sie diese in einer anderen Sprache als die Funktion 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 Lambda-Laufzeiten 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 Funktion auf zwei Arten Erweiterungen hinzufügen. Bei einer Funktion, die als .zip-Dateiarchivbereitgestellt wird, stellen Sie Ihre Erweiterung als Ebenebereit. Bei einer Funktion, die als Container-Image definiert ist, fügen Sie die Erweiterungen 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 signalisieren den Abschluss durch Senden einer Next API Anfrage. 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 Funktion registrieren. Dieses Limit wird durch den Register API Anruf durchgesetzt.

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 ist nach Ablauf der Laufzeit abgeschlossen, und jede registrierte Erweiterung zeigt den Abschluss an, indem sie eine Next API Anfrage sendet.

Invoke-Phase

Wenn eine Lambda-Funktion 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 Funktion ausgeführt. Sie werden auch weiter ausgeführt, nachdem die Funktion abgeschlossen ist. Auf diese Weise können Sie Diagnoseinformationen erfassen oder Protokolle, Metriken und Traces an einen Ort Ihrer Wahl senden.

Nachdem Erhalt der Funktionsantwort von der Laufzeitumgebung wird die Antwort von Lambda an den Client zurückgegeben, selbst wenn noch Erweiterungen ausgeführt werden.

Die Invoke Phase endet nach der Laufzeit und alle Erweiterungen signalisieren, dass sie fertig sind, indem sie eine Anfrage senden. Next API

Ereignisnutzlast: Das Ereignis, das an die Laufzeit (und die Lambda-Funktion) gesendet wird, trägt die gesamte Anforderung, Header (z. B. RequestId) und Nutzlast. 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 Funktion das Timeout (deadlineMs) überschreitet ()requestId, den Amazon-Ressourcennamen (ARN) der aufgerufenen Funktion und die Tracing-Header.

Erweiterungen, die auf den Hauptteil des Funktionsereignisses zugreifen möchten, können innerhalb der Laufzeit eine Funktion verwendenSDK, die mit der Erweiterung kommuniziert. Funktionsentwickler verwenden die Funktion während der LaufzeitSDK, um die Nutzdaten an die Erweiterung zu senden, wenn die Funktion 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"
    }
 }          

Begrenzung der Dauer: Die Timeout-Einstellung der Funktion begrenzt die Dauer der gesamten Invoke-Phase. Wenn Sie beispielsweise die Zeitüberschreitung für die Funktion auf 360 Sekunden festlegen, müssen die Funktion und alle Erweiterungen innerhalb von 360 Sekunden abgeschlossen werden. Beachten Sie, dass es keine unabhängige Post-Invoke-Phase gibt. Die Dauer ist die Gesamtzeit, die Ihre Laufzeit und alle Aufrufe Ihrer Erweiterungen benötigen. Sie wird erst berechnet, wenn die Funktion und alle Erweiterungen vollständig ausgeführt wurden.

Performance impact and extension overhead (Leistungsauswirkungen und Erweiterungsoverhead): Erweiterungen können sich auf die Funktionsleistung 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, erhöht sich die Dauer der Funktion, da sich die Erweiterung und der Funktionscode dieselben Ressourcen teilen. CPU Wenn Ihre Erweiterung umfangreiche Operationen ausführt, nachdem der Funktionsaufruf abgeschlossen ist, verlängert sich die Dauer des Funktionsaufrufs, da die Invoke-Phase fortgesetzt wird, 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 API Laufzeitanforderung und der letzten Next API Erweiterungsanforderung verbracht wurde. Verwenden Sie die MaxMemoryUsed-Metrik, um die Zunahme des verwendeten Speichers zu messen. Weitere Informationen zu Funktionsmetriken finden Sie unter Metriken für Lambda-Funktionen anzeigen.

Funktionsentwickler können verschiedene Versionen ihrer Funktionen nebeneinander ausführen, um die Auswirkungen einer bestimmten Erweiterung zu verstehen. Wir empfehlen, dass Erweiterungsautoren den erwarteten Ressourcenverbrauch veröffentlichen, um Funktionsentwicklern 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 Anfrage gesendet.

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

Für eine Funktion mit externen Erweiterungen reserviert Lambda bis zu 300 ms (500 ms für eine Laufzeit mit einer internen Erweiterung) für den Laufzeitprozess, um ein ordnungsgemäßes Abschalten durchführen zu können. Lambda weist den Rest der 2.000-ms-Grenze für das Herunterfahren externer Erweiterungen zu.

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-Funktion ausgeführt. Erweiterungen teilen sich mit der Funktion auch Ressourcen wie CPU Arbeitsspeicher und /tmp Festplattenspeicher. Darüber hinaus verwenden Erweiterungen dieselbe Rolle AWS Identity and Access Management (IAM) und denselben Sicherheitskontext wie die Funktion.

File system and network access permissions (Dateisystem- und Netzwerkzugriffsberechtigungen): Erweiterungen werden in demselben Dateisystem- und Netzwerk-Namespace wie die Funktionslaufzeit ausgeführt. Dies bedeutet, dass Erweiterungen mit dem zugehörigen Betriebssystem kompatibel sein müssen. Wenn für eine Erweiterung zusätzliche ausgehende Netzwerkverkehrsregeln erforderlich sind, müssen Sie diese Regeln auf die Funktionskonfiguration anwenden.

Environment variables (Umgebungsvariablen): Erweiterungen können auf die Umgebungsvariablen der Funktion 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.

Invoke failures (Aufruffehler) (z. B. kein Speicher mehr, Funktions-Timeout): Da Erweiterungen Ressourcen mit der Laufzeit gemeinsam nutzen, sind sie eventuell von Speichermangel betroffen. Wenn die Laufzeit ausfällt, nehmen alle Erweiterungen und die Laufzeit selbst an der Shutdown-Phase teil. Darüber hinaus wird die Laufzeitumgebung entweder automatisch als Teil des aktuellen Aufrufs oder über einen verzögerten Neuinitialisierungsmechanismus neu gestartet.

Wenn bei Invoke ein Fehler (z. B. eine Funktions-Zeitüberschreitung oder Laufzeitfehler) auftritt, führt der Lambda-Service einen Neustart 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

APIReferenz zu Erweiterungen

Die API Open-Spezifikation für die API Erweiterungsversion 2020-01-01 ist hier verfügbar: extensions-api.zip

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

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 Anfrage zum Empfang des nächsten Ereignisses, bei dem es sich um ein Invoke Ereignis oder ein Shutdown Ereignis handeln kann. Der Antworttext enthält die Payload, bei der es sich um ein JSON Dokument handelt, das Ereignisdaten enthält.

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

Legen Sie kein Timeout für den GET Anruf fest, da die Erweiterung für einen bestimmten Zeitraum unterbrochen werden kann, bis ein Ereignis eintrifft, das erneut stattfindet.

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 Lambda den Fehler erhalten hat, 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 Lambda den Fehler erhalten hat, 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": [ ]
}