Zugriff auf Echtzeit-Telemetriedaten für Erweiterungen über die Telemetrie-API

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.

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.

Über die Telemetry API können Ihre Erweiterungen Telemetriedaten direkt von Lambda empfangen. Während der Initialisierung und des Aufrufs von Funktionen erfasst Lambda automatisch Telemetriedaten wie Protokolle, Plattform-Metriken und Plattform-Ablaufverfolgungen. Über die Telemetry API können Erweiterungen diese Telemetriedaten direkt von Lambda in nahezu Echtzeit abrufen.

Sie können die Telemetrie-Streams für Ihre Lambda-Erweiterungen direkt in der Lambda-Ausführungsumgebung abonnieren. Nach dem Abonnement sendet Lambda automatisch alle Telemetriedaten an Ihre Erweiterungen. Sie können diese Daten dann verarbeiten, filtern und an Ihr bevorzugtes Ziel senden, z. B. einen Amazon Simple Storage Service (Amazon S3)-Bucket oder einen Drittanbieter von Beobachtbarkeits-Tools.

Das folgende Diagramm zeigt, wie die Extension API und die Telemetry API Erweiterungen von der Ausführungsumgebung aus mit Lambda verbinden. Die Runtime API verbindet zudem die Laufzeit und Funktion mit Lambda.

Erweiterungen können die Telemetrie-API verwenden, um drei verschiedene Telemetrie-Streams zu abonnieren:

Erstellen von Erweiterungen mithilfe der Telemetrie-API

Lambda-Erweiterungen werden als unabhängige Prozesse in der Ausführungsumgebung ausgeführt. Erweiterungen können nach Abschluss des Funktionsaufrufs weiter ausgeführt werden. Da Erweiterungen separate Prozesse sind, können Sie diese in einer anderen Sprache als dem Funktionscode schreiben. Es wird empfohlen, Erweiterungen mit einer kompilierten Sprache wie Golang oder Rust zu schreiben. Auf diese Weise ist die Erweiterung eine in sich geschlossene Binärdatei, die mit jeder unterstützten Laufzeitumgebung kompatibel sein kann.

Das folgende Diagramm zeigt einen vierstufigen Prozess zum Erstellen einer Erweiterung, die Telemetriedaten mithilfe der Telemetrie-API empfängt und verarbeitet.

Hier sind die einzelnen Schritte im Detail:

Registrieren Ihrer Erweiterung

Bevor Sie Telemetriedaten abonnieren können, müssen Sie Ihre Lambda-Erweiterung registrieren. Die Registrierung erfolgt während der Initialisierungsphase der Erweiterung. Das folgende Beispiel zeigt eine HTTP-Anfrage zur Registrierung einer Erweiterung.

POST http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
 Lambda-Extension-Name: lambda_extension_name
{
    'events': [ 'INVOKE', 'SHUTDOWN']
}

Wenn die Anfrage erfolgreich ist, erhält der Subscriber eine Erfolgsantwort von HTTP 200. Der Antwort-Header enthält den Lambda-Extension-Identifier. Der Antworttext enthält weitere Eigenschaften der Funktion.

HTTP/1.1 200 OK
Lambda-Extension-Identifier: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{
    "functionName": "lambda_function",
    "functionVersion": "$LATEST",
    "handler": "lambda_handler",
    "accountId": "123456789012"
}

Weitere Informationen hierzu finden Sie unter Erweiterungs-API-Referenz.

Erstellen eines Telemetrie-Listeners

Ihre Lambda-Erweiterung muss über einen Listener verfügen, der eingehende Anfragen der Telemetrie-API verarbeitet. Der folgende Code zeigt eine Beispielimplementierung eines Telemetrie-Listeners in Golang:

// Starts the server in a goroutine where the log events will be sent
func (s *TelemetryApiListener) Start() (string, error) {
	address := listenOnAddress()
	l.Info("[listener:Start] Starting on address", address)
	s.httpServer = &http.Server{Addr: address}
	http.HandleFunc("/", s.http_handler)
	go func() {
		err := s.httpServer.ListenAndServe()
		if err != http.ErrServerClosed {
			l.Error("[listener:goroutine] Unexpected stop on Http Server:", err)
			s.Shutdown()
		} else {
			l.Info("[listener:goroutine] Http Server closed:", err)
		}
	}()
	return fmt.Sprintf("http://%s/", address), nil
}

// http_handler handles the requests coming from the Telemetry API.
// Everytime Telemetry API sends log events, this function will read them from the response body
// and put into a synchronous queue to be dispatched later.
// Logging or printing besides the error cases below is not recommended if you have subscribed to
// receive extension logs. Otherwise, logging here will cause Telemetry API to send new logs for
// the printed lines which may create an infinite loop.
func (s *TelemetryApiListener) http_handler(w http.ResponseWriter, r *http.Request) {
	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		l.Error("[listener:http_handler] Error reading body:", err)
		return
	}

	// Parse and put the log messages into the queue
	var slice []interface{}
	_ = json.Unmarshal(body, &slice)

	for _, el := range slice {
		s.LogEventsQueue.Put(el)
	}

	l.Info("[listener:http_handler] logEvents received:", len(slice), " LogEventsQueue length:", s.LogEventsQueue.Len())
	slice = nil
}

Festlegen eines Zielprotokolls

Wenn Sie den Empfang von Telemetrie mithilfe der Telemetrie-API abonnieren, können Sie zusätzlich zur Ziel-URI ein Zielprotokoll angeben:

{
    "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
    }
}

Lambda akzeptiert zwei Protokolle für den Empfang von Telemetrie:

Bevor Sie sich für den Empfang von Telemetriedaten registrieren, richten Sie den lokalen HTTP-Listener oder TCP-Port ein. Beachten Sie bei der Einrichtung Folgendes:

Konfiguration der Speichernutzung und Pufferung

Der Speicherverbrauch in einer Ausführungsumgebung wächst linear mit der Anzahl der Abonnenten. Abonnements verbrauchen Speicherressourcen, da jedes einen neuen Speicherpuffer zum Speichern von Telemetriedaten öffnet. Die Pufferspeichernutzung wird zum Gesamtspeicherverbrauch in der Ausführungsumgebung gezählt.

Wenn Sie den Empfang von Telemetriedaten mithilfe der Telemetry API abonnieren, können Sie Telemetriedaten puffern und sie in Batches an Abonnenten übermitteln. Um die Speichernutzung zu optimieren, können Sie eine Pufferungskonfiguration angeben:

{
    "buffering": {
        "maxBytes": 256*1024,
        "maxItems": 1000,
        "timeoutMs": 100
    }
}

Beachten Sie beim Einrichten der Pufferung die folgenden Punkte:

Senden einer Abonnementanfrage an die Telemetrie-API

Lambda-Erweiterungen können den Empfang von Telemetriedaten abonnieren, indem sie eine Abonnementanfrage an die Telemetrie-API senden. Die Abonnementanfrage sollte Informationen über die Arten von Ereignissen enthalten, die die Erweiterung abonnieren soll. Darüber hinaus kann die Anfrage Informationen zum Lieferziel und eine Pufferkonfiguration enthalten.

Bevor Sie eine Abonnementanfrage senden, benötigen Sie eine Erweiterungs-ID (Lambda-Extension-Identifier). Wenn Sie Ihre Erweiterung in der Erweiterungs-API registrieren, erhalten Sie eine Erweiterungs-ID aus der API-Antwort.

Das Abonnement erfolgt während der Initialisierungsphase der Erweiterung. Das folgende Beispiel zeigt eine HTTP-Anfrage zum Abonnieren aller drei Telemetriestreams: Plattformtelemetrie, Funktionsprotokolle und Erweiterungsprotokolle.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
   "schemaVersion": "2022-12-13",
   "types": [
        "platform",
        "function",
        "extension"
   ],
   "buffering": {
        "maxItems": 1000,
        "maxBytes": 256*1024,
        "timeoutMs": 100
   },
   "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
   }
}

Ist die Anfrage erfolgreich, erhält der Subscriber eine HTTP 200-Erfolgsantwort.

HTTP/1.1 200 OK
"OK"

Eingehende Telemetrie-API-Nachrichten

Nach dem Abonnieren mit der Telemetry API beginnt eine Erweiterung automatisch, Telemetriedaten von Lambda über POST-Anfragen zu empfangen. Jeder POST-Anforderungstext enthält ein Array von Event Objekten. Jedes Event hat das folgende Schema:

{
   time: String,
   type: String,
   record: Object
}

Die folgende Tabelle fasst alle Event-Objekttypen zusammen und enthält Links zur Event-Telemetrie-API-Schemareferenz für jeden Ereignistyp.