Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Accès aux données de télémétrie en temps réel pour les extensions à l'aide de la télémétrie API

La télémétrie API permet à vos extensions de recevoir des données de télémétrie directement depuis Lambda. Pendant l'initialisation et l'invocation des fonctions, Lambda capture automatiquement la télémétrie, notamment les journaux, les métriques de la plateforme et les traces de la plateforme. La télémétrie API permet aux extensions d'accéder à ces données de télémétrie directement depuis Lambda en temps quasi réel.

Dans l'environnement d'exécution Lambda, vous pouvez abonner vos extensions Lambda à des flux de télémétrie. Après la souscription, Lambda envoie automatiquement toutes les données de télémétrie à vos extensions. Vous pouvez ensuite traiter, filtrer et distribuer les données à votre destination préférée, telle qu'un compartiment Amazon Simple Storage Service (Amazon S3) ou un fournisseur d'outils d'observabilité tiers.

Le schéma suivant montre comment les extensions API et la télémétrie API relient les extensions à Lambda depuis l'environnement d'exécution. De plus, le Runtime API connecte votre environnement d'exécution et votre fonction à Lambda.

Les extensions peuvent utiliser la télémétrie API pour s'abonner à trois flux de télémétrie différents :

Création d'extensions à l'aide de la télémétrie API

Les extensions Lambda s'exécutent comme des processus indépendants dans l'environnement d'exécution. Les extensions peuvent continuer à s'exécuter une fois l'invocation des fonctions terminée. Comme les extensions sont des processus séparés, vous pouvez les écrire dans un langage différent du code de la fonction. Nous recommandons d'écrire les extensions en utilisant un langage compilé tel que Golang ou Rust. De cette façon, l’extension est un binaire autonome qui peut être compatible avec tout environnement d’exécution pris en charge.

Le schéma suivant illustre un processus en quatre étapes pour créer une extension qui reçoit et traite les données de télémétrie à l'aide de la télémétrie. API

Voici chaque étape plus en détail :

Enregistrement de votre extension

Avant de pouvoir vous abonner aux données de télémétrie, vous devez enregistrer votre extension Lambda. L’enregistrement a lieu pendant la phase d’initialisation de l’extension. L'exemple suivant montre une HTTP demande d'enregistrement d'une extension.

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

Si la demande aboutit, l'abonné reçoit une réponse positive de HTTP 200. L’en-tête de réponse contient le Lambda-Extension-Identifier. Le corps de la réponse contient d’autres propriétés de la fonction.

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

Pour plus d’informations, consultez le APIRéférence des extensions.

Création d’un écouteur de télémétrie

Votre extension Lambda doit disposer d'un écouteur qui gère les demandes entrantes provenant de la télémétrie. API Le code suivant présente un exemple de mise en œuvre d’un écouteur de télémétrie en 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
}

Spécification d’un protocole de destination

Lorsque vous vous abonnez pour recevoir de la télémétrie à l'aide de la télémétrieAPI, vous pouvez spécifier un protocole de destination en plus de la destination : URI

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

Lambda accepte deux protocoles pour recevoir des télémétries :

Avant de vous abonner pour recevoir des données de télémétrie, définissez le port ou l'HTTPécouteur local. TCP Au cours de l’installation, notez ce qui suit :

Configuration de l’utilisation de la mémoire et de la mise en mémoire tampon

L'utilisation de la mémoire dans un environnement d'exécution augmente de façon linéaire avec le nombre d'abonnés. Les abonnements consomment des ressources de mémoire, car chacun d’eux ouvre un nouveau tampon mémoire pour stocker les données de télémétrie. L'utilisation de la mémoire tampon contribue à la consommation globale de mémoire dans l'environnement d'exécution.

Lorsque vous vous abonnez pour recevoir de la télémétrie par le biais de la télémétrieAPI, vous avez la possibilité de mettre en mémoire tampon les données de télémétrie et de les transmettre aux abonnés par lots. Pour optimiser l'utilisation de la mémoire, vous pouvez spécifier une configuration de mise en mémoire tampon :

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

Lorsque vous configurez la mise en mémoire tampon, tenez compte des points suivants :

Envoi d'une demande d'abonnement à la télémétrie API

Les extensions Lambda peuvent s'abonner pour recevoir des données de télémétrie en envoyant une demande d'abonnement à la télémétrie. API La demande d’abonnement doit contenir des informations sur les types d’événements auxquels vous voulez que l’extension s’abonne. En outre, la demande peut contenir des informations sur la destination de la livraison et une configuration de mise en mémoire tampon.

Avant d’envoyer une demande d’abonnement, vous devez disposer d’un ID d’extension (Lambda-Extension-Identifier). Lorsque vous enregistrez votre extension auprès des extensions API, vous obtenez un identifiant d'extension à partir de la API réponse.

L’abonnement a lieu pendant la phase d’initialisation de l’extension. L'exemple suivant montre une HTTP demande d'abonnement aux trois flux de télémétrie : télémétrie de plate-forme, journaux de fonctions et journaux d'extension.

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"
   }
}

Si la demande aboutit, l'abonné reçoit une réponse positive de HTTP 200.

HTTP/1.1 200 OK
"OK"

Messages de télémétrie API entrants

Après s'être abonnée à l'aide de la télémétrieAPI, une extension commence automatiquement à recevoir la télémétrie de Lambda via des requêtes. POST Chaque corps de POST requête contient un tableau d'Eventobjets. Chaque Event est structuré selon le schéma suivant :

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

Le tableau suivant récapitule tous les types d'Eventobjets et contient des liens vers la référence du API Event schéma de télémétrie pour chaque type d'événement.