API für Lambda-Protokolle - AWS Lambda
Abonnieren des Empfangs von ProtokollenSpeicherauslastungZiel-ProtokollePufferung der KonfigurationBeispielabonnementBeispielcode für Logs APILogs API-ReferenzProtokollmeldungen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

API für Lambda-Protokolle

Wichtig

Die Lambda-Telemetrie-API ersetzt die Lambda-Protokoll-API. Die Protokoll-API bleibt zwar voll funktionsfähig, wir empfehlen jedoch, in Zukunft nur die Telemetrie-API zu verwenden. Sie können Ihre Erweiterung für einen Telemetrie-Stream entweder über die Telemetrie-API oder die Protokoll-API abonnieren. Nach dem Abonnieren mithilfe einer dieser APIs gibt jeder Versuch, über die andere API zu abonnieren, einen Fehler zurück.

Lambda erfasst automatisch Laufzeitprotokolle und streamt sie an Amazon CloudWatch. Dieser Protokolldatenstream enthält die Protokolle, die Ihr Funktionscode und Ihre Erweiterungen generieren, sowie die Protokolle, die Lambda im Rahmen des Funktionsaufrufens generiert.

Lambda-Erweiterungen können die Lambda-Laufzeitprotokoll-API verwenden, um Protokollstreams direkt aus der Lambda-Ausführungsumgebung zu abonnieren. Lambda streamt die Protokolle zur Erweiterung und die Erweiterung kann die Protokolle dann an ein beliebiges bevorzugtes Ziel verarbeiten, filtern und senden.

Die Erweiterungs-API und die Protokoll-API verbinden Lambda mit externen Erweiterungen.

Die Logs API ermöglicht es Erweiterungen, drei verschiedene Protokollstreams zu abonnieren:

  • Funktionsprotokolle, die die Lambda-Funktion generiert und in stdout oder stderr schreibt.

  • Erweiterungsprotokolle, die der Erweiterungscode generiert.

  • Lambda-Plattformprotokolle, die Ereignisse und Fehler im Zusammenhang mit Aufrufen und Erweiterungen aufzeichnen.

Anmerkung

Lambda sendet alle Protokolle an CloudWatch, auch wenn eine Erweiterung einen oder mehrere der Protokollstreams abonniert.

Abonnieren des Empfangs von Protokollen

Eine Lambda-Erweiterung kann den Empfang von Protokollen abonnieren, indem sie eine Abonnementanfrage an die Protokoll-API sendet.

Um den Empfang von Protokollen zu abonnieren, benötigen Sie die Erweiterungskennung (Lambda-Extension-Identifier). Registrieren Sie zunächst die Erweiterung , um die Erweiterungskennung zu erhalten. Abonnieren Sie dann während der Initialisierung die Logs API. Lambda verarbeitet nach Abschluss der Initialisierungsphase keine Abonnementanfragen.

Anmerkung

Das Logs API-Abonnement ist idempotent. Doppelte Abonnementanfragen führen nicht zu doppelten Abonnements.

Speicherauslastung

Die Speichernutzung steigt linear, wenn die Anzahl der Abonnenten zunimmt. Abonnements verbrauchen Speicherressourcen, da jedes Abonnement einen neuen Speicherpuffer zum Speichern der Protokolle öffnet. Um die Speicherauslastung zu optimieren, können Sie die Pufferungskonfigurationanpassen. Die Pufferspeichernutzung wird zum Gesamtspeicherverbrauch in der Ausführungsumgebung gezählt.

Ziel-Protokolle

Sie können eines der folgenden Protokolle auswählen, um die Logs zu erhalten:

  1. HTTP (empfohlen) – Lambda stellt Protokolle als Array von Datensätzen im JSON-Format an einen lokalen HTTP-Endpunkt (http://sandbox.localdomain:${PORT}/${PATH}) bereit. Der Parameter $PATH ist optional. Beachten Sie, dass nur HTTP unterstützt wird, nicht HTTPS. Sie können wählen, ob Sie Logs über PUT oder POST erhalten möchten.

  2. TCP – Lambda stellt Protokolle an einen TCP-Port im Newline-delimited-JSON-(NDJSON)-Format bereit.

Wir empfehlen, HTTP statt TCP zu verwenden. Mit TCP kann die Lambda-Plattform nicht bestätigen, wenn es Protokolle an die Anwendungsebene übermittelt. Daher können Sie Protokolle verlieren, wenn Ihre Erweiterung abstürzt. Bei HTTP gilt diese Einschränkung nicht.

Wir empfehlen außerdem, den lokalen HTTP-Listener oder den TCP-Port einzurichten, bevor Sie sich für den Empfang von Protokollen anmelden. Beachten Sie bei der Einrichtung Folgendes:

  • Lambda sendet Protokolle nur an Ziele, die sich innerhalb der Ausführungsumgebung befinden.

  • Lambda wiederholt den Versuch, die Protokolle (mit Backoff) zu senden, wenn es keinen Listener gibt oder wenn die POST- oder PUT-Anfrage zu einem Fehler führt. Wenn der Protokollabonnent abstürzt, erhält er nach dem Neustart der Ausführungsumgebung durch Lambda weiterhin Protokolle.

  • Lambda reserviert Port 9001. Es gibt keine weiteren Einschränkungen oder Empfehlungen für Portnummern.

Pufferung der Konfiguration

Lambda kann Protokolle puffern und an den Abonnenten liefern. Sie können dieses Verhalten in der Abonnementanfrage konfigurieren, indem Sie die folgenden optionalen Felder angeben. Beachten Sie, dass Lambda den Standardwert für jedes Feld verwenden wird, das Sie nicht angeben.

  • timeoutMs – Die maximale Zeit (in Millisekunden) zum Puffern eines Batches. Standard: 1 000. Minimum: 25. Höchstwert: 30 000.

  • maxBytes – Die maximale Größe (in Byte) der Protokolle, die im Speicher gepuffert werden sollen. Standard: 262 144. Mindestwert: 262 144. Höchstwert: 1 048 576.

  • maxItems – Die maximale Anzahl der Ereignisse im Speicher, die gepuffert werden sollen. Standard: 10 000. Mindestwert 1 000. Höchstwert: 10 000.

Beachten Sie bei der Pufferung die folgenden Punkte:

  • Lambda bereinigt die Protokolle, wenn einer der Eingabestreams geschlossen wird, z. B. wenn die Laufzeit abstürzt.

  • Jeder Abonnent kann in seiner Abonnementanfrage eine andere Pufferungskonfiguration angeben.

  • Berücksichtigen Sie die Puffergröße, die Sie zum Lesen der Daten benötigen. Gehen Sie davon aus, dass die Nutzlasten so groß wie 2*maxBytes+metadata sein werden, wo maxBytes in der Abonnementanfrage konfiguriert ist. Lambda fügt beispielsweise jedem Datensatz die folgenden Metadaten-Bytes hinzu:

    {
"time": "2020-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}

  • Wenn der Abonnent eingehende Protokolle nicht schnell genug verarbeiten kann, wird Lambda Protokolle möglicherweise löschen, um die Speicherauslastung begrenzt zu halten. Um die Anzahl der gelöschten Datensätze anzugeben, schickt Lambda ein platform.logsDropped-Protokoll.

Beispielabonnement

Das folgende Beispiel zeigt eine Anfrage zum Abonnieren der Plattform- und Funktionsprotokolle.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs HTTP/1.1
{ "schemaVersion": "2020-08-15",
  "types": [
      "platform",
      "function"
    ],
  "buffering": {
      "maxItems": 1000,
      "maxBytes": 262144,
      "timeoutMs": 100
    },
  "destination": {
    "protocol": "HTTP",
    "URI": "http://sandbox.localdomain:8080/lambda_logs"
  }
}

Wenn die Anfrage erfolgreich ist, erhält der Abonnent eine Erfolgsantwort von HTTP 200.

HTTP/1.1 200 OK
"OK"

Beispielcode für Logs API

Beispielcode zum Senden von Protokollen an ein benutzerdefiniertes Ziel finden Sie unter Verwenden von AWS Lambda-Erweiterungen zum Senden von Protokollen an benutzerdefinierte Ziele im AWS-Compute-Blog.

Codebeispiele für Python und Go, die zeigen, wie Sie eine grundlegende Lambda-Erweiterung entwickeln und die Logs-API abonnieren, finden Sie unter AWS Lambda Erweiterungen im AWS -Beispiel- GitHub Repository. Für weitere Informationen zum Erstellen einer Lambda-Erweiterung siehe Verwenden der Lambda Extensions API zum Erstellen von Erweiterungen.

Logs API-Referenz

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

http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs

Die OpenAPI-Spezifikation für die Logs-API-Version 2020-08-15 ist hier verfügbar: logs-api-request.zip

Abonnieren

Um einen oder mehrere der in der Lambda-Ausführungsumgebung verfügbaren Protokollstreams zu abonnieren, senden Erweiterungen eine Abonnement-API-Anforderung.

Pfad – /logs

Methode – PUT

Body-Parameter

destination – Siehe Ziel-Protokolle. Erforderlich: ja Typ: Strings.

buffering – Siehe Pufferung der Konfiguration. Erforderlich: Nein Typ: Strings.

types – Ein Array der zu empfangenden Protokollentypen. Erforderlich: ja Typ: Zeichenfolge-Array Gültige Werte: „platform“, „function“, „extension“.

schemaVersion – Erforderlich: Nein. Standardwert: „2020-08-15“. Stellen Sie „2021-03-18“ ein, damit die Erweiterung platform.runtimeDone-Meldungen empfangen kann.

Antwortparameter

Die OpenAPI-Spezifikationen für die Abonnementantworten, Version 2020-08-15, stehen für HTTP- und TCP-Protokolle zur Verfügung:

Antwortcodes

  • 200 – Anfrage erfolgreich abgeschlossen

  • 202 – Anfrage wurde akzeptiert. Antwort auf eine Abonnementanfrage während lokaler Tests.

  • 4XX – Ungültige Anfrage

  • 500 – Servicefehler

Wenn die Anfrage erfolgreich ist, erhält der Abonnent eine Erfolgsantwort von HTTP 200.

HTTP/1.1 200 OK
"OK"

Schlägt die Anfrage fehl, erhält der Abonnent eine Fehlerantwort. Zum Beispiel:

HTTP/1.1 400 OK
{
    "errorType": "Logs.ValidationError",
    "errorMessage": URI port is not provided; types should not be empty"
}

Protokollmeldungen

Die Logs API ermöglicht es Erweiterungen, drei verschiedene Protokollstreams zu abonnieren:

  • Funktion – Protokolle, die die Lambda-Funktion generiert und in stdout oder stderr schreibt.

  • Erweiterung – Protokolle, die der Erweiterungscode generiert.

  • Plattform – Protokolle, die von der Laufzeitplattform generiert werden und die Ereignisse und Fehler im Zusammenhang mit Aufrufen und Erweiterungen aufzeichnen.

Funktionsprotokolle

Die Lambda-Funktion und interne Erweiterungen generieren Funktionsprotokolle und schreiben sie in stdout oder stderr.

Das folgende Beispiel zeigt das Format einer Funktionsprotokollmeldung. {„time“: „2020-08-20T12:31:32.123Z“, „type“: „function“, „record“: „ERROR encountered. Stack trace:\n\my-function (line 10)\n" }

Erweiterungsprotokolle

Erweiterungen können Erweiterungsprotokolle generieren. Das Protokollformat ist das gleiche wie bei einem Funktionsprotokoll.

Plattformprotokolle

Lambda generiert Protokollmeldungen für Plattformereignisse wie platform.start, platform.end und platform.fault.

Optional können Sie die Version 2021-03-18 des Logs API-Schemas abonnieren, welche die platform.runtimeDone-Protokollmeldungen enthält.

Beispiel für Plattformprotokollmeldungen

Das folgende Beispiel zeigt die Plattformstart- und Plattformendprotokolle. Diese Protokolle zeigen die Startzeit des Aufrufs und die Endzeit des Aufrufs für den Aufruf an, den die RequestID angibt. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.start",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}   
}
{
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.end",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}   
}

Die platform.initRuntimeDone-Protokollmeldung zeigt den Status der Runtime init Unterphase an, die Teil der Init-Lebenszyklusphase ist. Wenn Runtime init erfolgreich ist, sendet die Laufzeit eine /next-Laufzeit-API-Anfrage (für die on-demand- und provisioned-concurrency-Initialisierungstypen) oder restore/next (für den snap-start-Initialisierungstyp). Das folgende Beispiel zeigt eine erfolgreiche platform.initRuntimeDone-Protokollmeldung für den -snap-startInitialisierungstyp.

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initRuntimeDone",
  "record":{
      "initializationType":"snap-start",
      "status":"success"
  }
}

Die platform.initReport-Protokollnachricht zeigt, wie lange die Init-Phase gedauert hat und wie viele Millisekunden Ihnen während dieser Phase in Rechnung gestellt wurden. Wenn der Initialisierungstyp provisioned-concurrency lautet, sendet Lambda diese Nachricht während des Aufrufs. Wenn der Initialisierungstyp snap-start lautet, sendet Lambda diese Nachricht nach der Wiederherstellung des Snapshots. Das folgende Beispiel zeigt eine platform.initReport-Protokollnachricht für den snap-start-Initialisierungstyp.

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initReport",
  "record":{
      "initializationType":"snap-start",
      "metrics":{
          "durationMs":731.79,
          "billedDurationMs":732
          }
  }
}

Das Berichtsprotokoll der Plattform enthält Metriken über den Aufruf, den die RequestID angibt. Das initDurationMs-Feld ist nur dann im Protokoll enthalten, wenn der Aufruf einen Kaltstart enthielt. Wenn die AWS X-Ray-Ablaufverfolgung aktiv ist, enthält das Protokoll X-Ray-Metadaten. Das folgende Beispiel zeigt ein Plattformberichtsprotokoll für einen Aufruf, der einen Kaltstart enthielt.

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.report",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56",
        "metrics": {"durationMs": 101.51,
            "billedDurationMs": 300,
            "memorySizeMB": 512,
            "maxMemoryUsedMB": 33,
            "initDurationMs": 116.67
        }
    }
}

Das Plattformfehlerprotokoll erfasst Fehler bei der Laufzeit oder der Ausführungsumgebung. Das folgende Beispiel zeigt eine Fehlerprotokollmeldung der Plattform. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.fault",
    "record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before completing request"
}

Lambda generiert ein Plattformerweiterungsprotokoll, wenn sich eine Erweiterung bei der Erweiterungs-API registriert. Das folgende Beispiel zeigt eine Plattformerweiterungsmeldung. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.extension",
    "record": {"name": "Foo.bar",
        "state": "Ready",
        "events": ["INVOKE", "SHUTDOWN"]
     }
}

Lambda generiert ein Plattformprotokoll-Abonnementprotokoll, wenn eine Erweiterung die Protokoll-API abonniert. Das folgende Beispiel zeigt eine Protokoll-Abonnementmeldung. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.logsSubscription",
    "record": {"name": "Foo.bar",
        "state": "Subscribed",
        "types": ["function", "platform"],
    }
}

Lambda generiert ein vom Plattformprotokoll abgelegtes Protokoll, wenn eine Erweiterung nicht in der Lage ist, die Anzahl der Protokolle zu verarbeiten, die sie empfängt. Das folgende Beispiel zeigt eine platform.logsDropped-Protokollmeldung. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.logsDropped",
    "record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged receipt of logs.",
        "droppedRecords": 123,
        "droppedBytes" 12345
    }
}

Die platform.restoreStart-Protokollnachricht zeigt den Zeitpunkt an, zu dem die Restore-Phase begonnen hat (nur snap-start-Initialisierungstyp). Beispiel:

{ 
  "time":"2022-07-17T18:43:44.782Z", 
  "type":"platform.restoreStart", 
  "record":{} 
}

Die platform.restoreReport-Protokollnachricht zeigt, wie lange die Restore-Phase gedauert hat und wie viele Millisekunden Ihnen während dieser Phase in Rechnung gestellt wurden (nur snap-start-Initialisierungstyp). Beispiel:

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreReport",
  "record":{
      "metrics":{
          "durationMs":70.87,
          "billedDurationMs":13
      }
  }
}

Plattform runtimeDone-Meldungen

Wenn Sie die Schemaversion in der Abonnementanforderung auf „2021-03-18“ setzen, schickt Lambda eine platform.runtimeDone-Meldung, nachdem der Funktionsaufruf entweder erfolgreich oder mit einem Fehler abgeschlossen wurde. Die Erweiterung kann diese Meldung verwenden, um die gesamte Telemetrie-Sammlung für diesen Funktionsaufruf anzuhalten.

Die OpenAPI-Spezifikation für den Protokollereignistyp in der Schemaversion 2021-03-18 ist hier verfügbar: schema-2021-03-18.zip

Lambda generiert die platform.runtimeDone-Protokollmeldung, wenn die Laufzeitumgebung eine Next- oder Error-Laufzeit-API-Anforderung sendet. Das platform.runtimeDone-Protokoll informiert die Verbraucher über die Protokoll-API, dass der Funktionsaufruf abgeschlossen ist. Erweiterungen können diese Informationen verwenden, um zu entscheiden, wann die gesamte während dieses Aufrufs gesammelte Telemetrie gesendet werden soll.

Beispiele

Lambda sendet die platform.runtimeDone-Meldung, nachdem die Laufzeit die NEXT-Anfrage sendet, wenn der Funktionsaufruf abgeschlossen wird. Die folgenden Beispiele zeigen Meldungen für jeden der Statuswerte: Erfolg, Misserfolg und Timeout.

Beispiel Erfolgsmeldung
{
    "time": "2021-02-04T20:00:05.123Z",
    "type": "platform.runtimeDone",
    "record": {
       "requestId":"6f7f0961f83442118a7af6fe80b88",
       "status": "success"
    }
}
Beispiel Misserfolgsmeldung
{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "failure"
   }
}
Beispiel Timeout-Meldung 
{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "timeout"
  }
}
Beispiel für platform.restoreRuntimeDone message (snap-startnur -Initialisierungstyp)

Die platform.restoreRuntimeDone-Protokollmeldung zeigt, ob die -RestorePhase erfolgreich war oder nicht. Lambda sendet diese Nachricht, wenn die Laufzeit eine restore/next-Laufzeit-API-Anfrage sendet. Es gibt drei mögliche Status: erfolgreich, fehlgeschlagen und Timeout. Das folgende Beispiel zeigt eine erfolgreiche platform.restoreRuntimeDone-Protokollmeldung.

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreRuntimeDone",
  "record":{
      "status":"success"
  }
}