API de télémétrie Lambda

L'API de télémétrie active vos extensions pour recevoir directement des données de télémétrie de 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. L'API de télémétrie active des extensions pour 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 l'API d'extensions et l'API de télémétrie lient les extensions à Lambda depuis l'environnement d'exécution. De plus, l'API d'exécution connecte votre environnement d'exécution et votre fonction à Lambda.

Important

L’API de télémétrie Lambda remplace l’API de journaux Lambda. Bien que l’API de journaux reste entièrement fonctionnelle, nous vous recommandons d’utiliser uniquement l’API de télémétrie à l’avenir. Vous pouvez abonner votre extension à un flux de télémétrie en utilisant l’API de télémétrie ou l’API de journaux. Après s’être abonné à l’aide de l’une de ces API, toute tentative d’abonnement à l’aide de l’autre API renvoie une erreur.

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

• Télémétrie de plateforme – Journaux, métriques et traces, qui décrivent les événements et les erreurs liés au cycle de vie de l’environnement d’exécution, au cycle de vie des extensions et aux appels de fonctions

• Journaux de fonction – Journaux personnalisés que le code de la fonction Lambda génère.

• Journaux d’extension – Journaux personnalisés générés par le code d’extension Lambda.

Note

Lambda envoie des journaux CloudWatch, des métriques et des traces à X-Ray (si vous avez activé le suivi), même si une extension s'abonne à des flux de télémétrie.

Sections

• Création d’extensions à l’aide de l’API de télémétrie
• Enregistrement de votre extension
• Création d’un écouteur de télémétrie
• Spécification d’un protocole de destination
• Configuration de l’utilisation de la mémoire et de la mise en mémoire tampon
• Envoi d’une demande d’abonnement à l’API de télémétrie
• Messages entrants de l’API de télémétrie
• Référence de l’API de télémétrie Lambda
• Référence du schéma Event de l’API de télémétrie Lambda
• Conversion d'objets de l'API de télémétrie Lambda en Spans Event OpenTelemetry
• API Logs Lambda

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

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 des données de télémétrie à l’aide de l’API de télémétrie.

Voici chaque étape plus en détail :

1. Enregistrez votre extension à l’aide du Utilisation de l'API Lambda Extensions pour créer des extensions. Cela vous fournit un Lambda-Extension-Identifier, dont vous aurez besoin dans les étapes suivantes. Pour plus d’informations sur la façon d’enregistrer votre extension, consultez Enregistrement de votre extension.

2. Créez un écouteur de télémétrie. Il peut s’agir d’un serveur HTTP ou TCP de base. Lambda utilise l’URI de l’écouteur de télémétrie pour envoyer des données de télémétrie à votre extension. Pour plus d’informations, consultez Création d’un écouteur de télémétrie.

3. À l'aide de l'API d'abonnement de l'API de télémétrie, abonnez votre extension aux flux de télémétrie souhaités. Vous aurez besoin de l’URI de votre écouteur de télémétrie pour cette étape. Pour plus d’informations, consultez Envoi d’une demande d’abonnement à l’API de télémétrie.

4. Obtenez les données de télémétrie de Lambda via l’écouteur de télémétrie. Vous pouvez effectuer tout traitement personnalisé de ces données, par exemple en les envoyant vers Amazon S3 ou vers un service d’observabilité externe.

Note

L’environnement d’exécution d’une fonction Lambda peut démarrer et s’arrêter plusieurs fois dans le cadre de son cycle de vie. En général, votre code d’extension s’exécute pendant les appels de la fonction, et aussi jusqu’à 2 secondes pendant la phase d’arrêt. Nous vous recommandons de regrouper la télémétrie au fur et à mesure qu'elle parvient à votre écouteur. Utilisez ensuite les événements du cycle de vie Invoke et Shutdown pour envoyer chaque lot vers les destinations souhaitées.

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 demande HTTP pour enregistrer 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 réussit, l’abonné reçoit une réponse de succès 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 Référence d’API d’extensions.

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

Votre extension Lambda doit avoir un écouteur qui traite les demandes entrantes de l’API de télémétrie. 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 l’API de télémétrie, vous pouvez spécifier un protocole de destination en plus de l’URI de destination :

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

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

• HTTP (recommandé) – Lambda envoie la télémétrie à un point de terminaison HTTP local (http://sandbox.localdomain:${PORT}/${PATH}) sous la forme d’un tableau d’enregistrements au format JSON. Le paramètre $PATH est facultatif. Lambda ne prend en charge que HTTP, pas HTTPS. Lambda fournit des données de télémétrie via des demandes POST.

• TCP – Lambda envoie la télémétrie à un port TCP au format NDJSON (Newline delimited JSON).

Note

Nous vous recommandons vivement d’utiliser HTTP plutôt que TCP. Avec TCP, la plateforme Lambda ne peut pas confirmer la livraison de la télémétrie à la couche d’application. Par conséquent, si votre extension se bloque, vous risquez de perdre la télémétrie. HTTP ne présente pas cette limitation.

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

• Lambda n’envoie la télémétrie qu’à des destinations au sein de l’environnement d’exécution.

• Lambda réessaie d'envoyer la télémétrie (avec interruption) en l'absence d'écouteur, ou si la demande POST rencontre une erreur. Si l'écouteur de télémétrie se bloque, il reprend la réception de la télémétrie après que Lambda a redémarré l'environnement d'exécution.

• Lambda réserve le port 9001. Il n’y a pas d’autres restrictions ou recommandations relatives au numéro de port.

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 des données télémétriques via l'API de télémétrie, vous pouvez mettre en mémoire tampon les données télémétriques et 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
    }
}

Paramètres de configuration de la mise en mémoire tampon
Paramètre	Description	Valeurs par défaut et limites
maxBytes	Le volume maximal de télémétrie (en octets) à mettre en mémoire tampon.	Par défaut : 262 144 Minimum : 262 144 Maximum : 1 048 576
maxItems	Le nombre maximal d’événements à mettre en mémoire tampon.	Par défaut : 10 000 Minimum : 1 000 Maximum : 10 000.
timeoutMs	La durée maximale (en millisecondes) pour la mise en mémoire tampon d’un lot.	Par défaut : 1 000 Minimum : 25 Maximum : 30 000

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

• Si l'un des flux d'entrée est fermé, Lambda vide les journaux. Cela peut se produire si, par exemple, l'environnement d'exécution se bloque.

• Chaque abonné peut spécifier une configuration de mise en mémoire tampon différente dans sa demande d'abonnement.

• Lorsque vous déterminez la taille de la mémoire tampon pour la lecture des données, attendez-vous à recevoir des charges utiles aussi importantes que 2 * maxBytes + metadataBytes, maxBytes étant un composant de votre configuration de mise en mémoire tampon. Pour évaluer la quantité de metadataBytes à prendre en compte, consultez les métadonnées suivantes. Lambda adjoint des métadonnées similaires à celles-ci à chaque enregistrement :

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

• Si l’abonné ne peut pas traiter la télémétrie entrante assez rapidement, ou si votre code de fonction génère un volume de journal très élevé, Lambda peut abandonner des enregistrements pour limiter l’utilisation de la mémoire. Lorsque cela se produit, Lambda envoie un événement platform.logsDropped.

Envoi d’une demande d’abonnement à l’API de télémétrie

Les extensions Lambda peuvent s’abonner pour recevoir des données de télémétrie en envoyant une demande d’abonnement à l’API de télémétrie. 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 avec l’API d’extensions, vous obtenez un ID d’extension à partir de la réponse API.

L’abonnement a lieu pendant la phase d’initialisation de l’extension. L’exemple suivant montre une demande HTTP pour s’abonner aux trois flux de télémétrie : télémétrie de la plateforme, journaux des fonctions et journaux des extensions.

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 réussit, l’abonné reçoit une réponse de succès HTTP 200.

HTTP/1.1 200 OK
"OK"

Messages entrants de l’API de télémétrie

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

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

• La propriété time définit le moment où la plateforme Lambda a généré l’événement. Cela est différent du moment où l'événement s'est réellement produit. La valeur de la chaîne time est un horodatage au format ISO 8601.

• La propriété type définit le type d’événement. Le tableau suivant décrit toutes les valeurs possibles.

• La propriété record définit un objet JSON qui contient les données de télémétrie. Le schéma de cet objet JSON dépend de la propriété type.

Le tableau suivant résume tous les types d’objets Event et renvoie à la référence du schéma Event de l’API de télémétrie pour chaque type d’événement.

Types de messages de l’API de télémétrie
Catégorie	Type d’événement	Description	Schéma d’enregistrement des événements
Événement de plateforme	platform.initStart	L’initialisation de la fonction a commencé.	Schéma platform.initStart
Événement de plateforme	platform.initRuntimeDone	L’initialisation de la fonction est terminée.	Schéma platform.initRuntimeDone
Événement de plateforme	platform.initReport	Un rapport d’initialisation de la fonction.	Schéma platform.initReport
Événement de plateforme	platform.start	L’invocation de la fonction a commencé.	Schéma platform.start
Événement de plateforme	platform.runtimeDone	L’environnement d’exécution a fini de traiter un événement avec succès ou échec.	Schéma platform.runtimeDone
Événement de plateforme	platform.report	Un rapport sur l’invocation de la fonction.	Schéma platform.report
Événement de plateforme	platform.restoreStart	La restauration de l’exécution a commencé.	Schéma platform.restoreStart
Événement de plateforme	platform.restoreRuntimeDone	La restauration de l’exécution est terminée.	Schéma platform.restoreRuntimeDone
Événement de plateforme	platform.restoreReport	Le rapport de restauration de d’exécution.	Schéma platform.restoreReport
Événement de plateforme	platform.telemetrySubscription	L’extension s’est abonnée à l’API de télémétrie.	Schéma platform.telemetrySubscription
Événement de plateforme	platform.logsDropped	Les entrées de journal abandonnées par Lambda.	Schéma platform.logsDropped
Journaux de fonctions	function	Une ligne de journal du code de la fonction.	Schéma function
Journaux d’extension	extension	Une ligne de journal du code de l’extension.	Schéma extension