API Logs 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.

Lambda capture automatiquement les journaux d'exécution et les diffuse vers Amazon. CloudWatch Ce flux de journaux contient les journaux que génèrent votre code de fonction et vos extensions, ainsi que les journaux que Lambda génère dans le cadre de l'appel de fonction.

Les extensions Lambda peuvent utiliser l'API Lambda Runtime Logs pour s'abonner à des flux de journaux directement à partir de l'environnement d'exécution Lambda. Lambda diffuse les journaux vers l'extension qui peut ensuite les traiter, les filtrer et les envoyer à n'importe quelle destination de prédilection.

L'API Logs permet aux extensions de s'abonner à trois flux de journaux différents :

• Journaux de fonction que la fonction Lambda génère et écrit dans stdout ou stderr.

• Journaux d'extension que le code d'extension génère.

• Journaux de plateforme Lambda qui enregistrent les événements et les erreurs liés aux appels et aux extensions.

Note

Lambda envoie tous les journaux à CloudWatch, même lorsqu'une extension s'abonne à un ou plusieurs flux de journaux.

S'abonner pour recevoir des journaux

Une extension Lambda peut s'abonner aux journaux en envoyant une demande d'abonnement à l'API Logs.

Pour vous abonner afin de recevoir des journaux, vous avez besoin de l'identifiant d'extension (Lambda-Extension-Identifier). Enregistrez d'abord l'extension pour recevoir l'identifiant de l'extension. Abonnez-vous ensuite à l'API Logs lors de l'initialisation. Une fois la phase d'initialisation terminée, Lambda ne traite pas les demandes d'abonnement.

Note

L'abonnement à l'API Logs est idempotent. Les demandes d'abonnement en double n'entraînent pas de doublons d'abonnements.

Utilisation de la mémoire

L'utilisation de la mémoire augmente de façon linéaire à mesure que le nombre d'abonnés augmente. Les abonnements consomment des ressources de mémoire car chaque abonnement ouvre un nouveau tampon mémoire pour stocker les journaux. Pour optimiser l'utilisation de la mémoire tampon, vous pouvez ajuster la configuration de la mise en mémoire tampon. L'utilisation de la mémoire tampon compte pour la consommation globale de mémoire dans l'environnement d'exécution.

Protocoles de destination

Vous pouvez choisir l'un des protocoles suivants pour recevoir les journaux :

1. HTTP (recommandé) – Lambda envoie les journaux à 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. Notez que seul HTTP est pris en charge, pas HTTPS. Vous pouvez choisir de recevoir des journaux via PUT ou POST.

2. TCP – Lambda envoie les journaux à un port TCP au format NDJSON (Newline delimited JSON).

Nous vous recommandons d'utiliser HTTP plutôt que TCP. Avec TCP, la plateforme Lambda ne peut pas confirmer la livraison des journaux à la couche d'application. Vous risquez par conséquent de perdre des journaux si votre extension se bloque. HTTP ne partage pas cette limitation.

Nous vous recommandons également de configurer l'écouteur HTTP local ou le port TCP avant de vous abonner pour recevoir les journaux. Au cours de l'installation, notez ce qui suit :

• Lambda n'envoie de journaux qu'à des destinations au sein de l'environnement d'exécution.

• Lambda réessaie d'envoyer les journaux (avec une interruption) s'il n'y a pas d'écouteur, ou si la requête POST ou PUT génère une erreur. Si l'abonné aux journaux se bloque, il continue de recevoir des journaux 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 mise en mémoire tampon

Lambda peut mettre les journaux en mémoire tampon avant de les livrer à l'abonné. Vous pouvez configurer ce comportement dans la demande d'abonnement en spécifiant les champs facultatifs suivants. Notez que Lambda utilise la valeur par défaut pour tout champ que vous ne spécifiez pas.

• timeoutMs – Durée maximum (en millisecondes) de mise en mémoire tampon d’un lot. Par défaut : 1 000. Minimum : 25. Maximum : 30 000.

• maxBytes – Taille maximum (en octets) des journaux à mettre en mémoire tampon. Par défaut : 262 144. Minimum : 262 144. Maximum : 1 048 576.

• maxItems – Nombre maximum d'événements à mettre en mémoire tampon. Par défaut : 10 000. Minimum : 1 000. Maximum : 10 000.

Lors de la configuration de la mise en mémoire tampon, notez les points suivants :

• Lambda vide les journaux en cas de fermeture de l'un des flux d'entrée, par exemple, si le runtime se bloque.

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

• Tenez compte de la taille de tampon dont vous avez besoin pour lire les données. Attendez-vous à recevoir des charges utiles aussi volumineuses que 2*maxBytes+metadata, où maxBytes est configuré dans la demande d'abonnement. Par exemple, Lambda ajoute les octets de métadonnées suivants à chaque enregistrement :

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

• Si l'abonné ne peut pas traiter les journaux entrants assez rapidement, Lambda peut supprimer les journaux pour limiter l'utilisation de la mémoire. Pour indiquer le nombre d'enregistrements supprimés, Lambda envoie un journal platform.logsDropped.

Exemple d'abonnement

L'exemple suivant montre une demande d'abonnement aux journaux de la plateforme et des fonctions.

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

Si la demande réussit, l'abonné reçoit une réponse de succès HTTP 200.

HTTP/1.1 200 OK
"OK"      

Exemple de code pour l'API Logs

Pour obtenir un exemple de code qui montre comment envoyer des journaux à une destination personnalisée, consultez l'article Using AWS Lambda extensions to send logs to custom destinations du blog AWS Compute.

Pour des exemples de code Python et Go montrant comment développer une extension Lambda de base et s'abonner à l'API Logs, voir AWS LambdaExtensions dans le référentiel AWS Samples GitHub . Pour plus d'informations sur la génération d’une extension Lambda, consultez API Extensions Lambda.

Référence d'API Logs

Vous pouvez extraire le point de terminaison d'API Logs à partir de la variable d'environnement AWS_LAMBDA_RUNTIME_API. Pour envoyer une demande d’API, utilisez le préfixe 2020-08-15/ avant le chemin d'accès de l'API. Par exemple :

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

La spécification OpenAPI pour la version 2020-08-15 de l'API Logs est disponible ici : .zip logs-api-request

S’abonner

Pour s'abonner à un ou plusieurs des flux de journal disponibles dans l'environnement d'exécution Lambda, les extensions envoient une demande d'API Subscribe.

Chemin – /logs

Méthode – PUT

Paramètres de corps

destination – Voir Protocoles de destination. Obligatoire : oui. Type : chaînes.

buffering – Voir Configuration de mise en mémoire tampon. Requis : non. Type : chaînes.

types – Tableau des types de journaux à recevoir. Obligatoire : oui. Type : tableau de chaînes. Valeurs valides : « plateforme », « fonction», « extension ».

schemaVersion – Obligatoire : non. Valeur par défaut : « 2020-08-15 ». Attribuez la valeur « 2021-03-18 » pour que l'extension reçoive les messages platform.runtimeDone.

Paramètres de réponse

Les spécifications OpenAPI pour les réponses d'abonnement version 2020-08-15 sont disponibles pour les protocoles HTTP et TCP :

• HTTP : logs-api-http-response.zip

• TCP : .zip logs-api-tcp-response

Codes de réponse

• 200 – Demande effectuée avec succès.

• 202 – Demande acceptée. Réponse à une demande d'abonnement pendant les tests locaux.

• 4XX – Demande erronée.

• 500 – Erreur de service.

Si la demande réussit, l'abonné reçoit une réponse de succès HTTP 200.

HTTP/1.1 200 OK
"OK"      

Si la demande échoue, l'abonné reçoit une réponse d'erreur. Exemples :

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

Messages de journaux

L'API Logs permet aux extensions de s'abonner à trois flux de journaux différents :

• Fonction – Journaux que la fonction Lambda génère et écrit dans stdout ou stderr.

• Extension – Journaux que le code d'extension génère.

• Plateforme – Journaux que la plateforme de runtime génère, qui consignent des événements et des erreurs liés aux appels et aux extensions.

Rubriques

• Journaux de fonctions
• Journaux d'extension
• Journaux de plateforme

Journaux de fonctions

La fonction Lambda et les extensions internes génèrent des journaux de fonction et les écrivent dans stdout ou stderr.

L'exemple suivant montre le format d'un message de journal de fonction. { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\n\my-function (line 10)\n" }

Journaux d'extension

Les extensions peuvent générer des journaux d'extensions. Le format du journal est le même que pour un journal de fonction.

Journaux de plateforme

Lambda génère des messages de journal pour des événements de plateforme tels que platform.start, platform.end et platform.fault.

Vous pouvez éventuellement vous abonner à la version 2021-03-18 du schéma de l'API Logs, qui inclut le message de journal platform.runtimeDone.

Exemple de messages du journal de la plateforme

L'exemple suivant montre les journaux de début et de fin de la plateforme. Ces journaux indiquent l'heure de début et de fin de l'appel pour l'appel spécifié par le requestId.

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

La plateforme. initRuntimeDoneun message de journal indique l'état de la Runtime init sous-phase, qui fait partie de la phase du cycle de vie d'initialisation. Lorsque Runtime init est réussie, l'environnement d'exécution envoie une demande d'API d'exécution /next (pour les types d'initialisation on-demand et provisioned-concurrency) ou restore/next (pour le type d'initialisation snap-start). L'exemple suivant montre une plateforme performante. initRuntimeDonemessage de journal pour le type snap-start d'initialisation.

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

Le message de journal platform.initReport indique la durée de la phase Init et le nombre de millisecondes qui vous ont été facturées pendant cette phase. Lorsque le type d'initialisation est provisioned-concurrency, Lambda envoie ce message pendant l'appel. Lorsque le type d'initialisation est snap-start, Lambda envoie ce message après avoir restauré l'instantané. L'exemple suivant montre un message de journal platform.initReport pour le type d'initialisation snap-start.

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

Le journal du rapport de la plateforme inclut des métriques relatives à l'appel spécifié par le requestId. Le champ initDurationMs n'est inclus dans le journal que si l'appel comprend un démarrage à froid. Si le suivi AWS X-Ray est actif, le journal inclut les métadonnées X-Ray. L'exemple suivant montre un journal de rapport de la plateforme pour un appel qui comprend un démarrage à froid.

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

Le journal des pannes de la plateforme capture les erreurs d'exécution ou d'environnement d'exécution. L'exemple suivant montre un message de journal des erreurs de plateforme.

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

Lambda génère un journal d'extension de plateforme quand une extension s'enregistre auprès de l'API d'extensions. L'exemple suivant montre un message d'extension de la plateforme.

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

Lambda génère un journal d'abonnement aux journaux de plateforme quand une extension s'abonne à l'API Logs. L'exemple suivant montre un message d'abonnement aux journaux.

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

Lambda génère un journal des journaux de plateforme supprimés quand une extension n'est pas en mesure de traiter le nombre de journaux qu'elle reçoit. L'exemple suivant montre un message de journal platform.logsDropped.

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

Le message de journal platform.restoreStart indique l'heure à laquelle la phase Restore a démarré (type d'initialisation snap-start uniquement). Exemple :

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

Le message de journal platform.restoreReport indique la durée de la phase Restore et le nombre de millisecondes qui vous ont été facturées pendant cette phase (type d'initialisation snap-start uniquement). Exemple :

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

Messages runtimeDone de plateforme

Si vous définissez la version du schéma sur « 2021-03-18 » dans la demande d'abonnement, Lambda envoie un message platform.runtimeDone une fois l'appel de fonction terminé avec succès ou avec une erreur. L'extension peut utiliser ce message pour arrêter toute la collecte de données télémétriques pour cet appel de fonction.

La spécification OpenAPI pour le type d'événement Log dans la version de schéma 2021-03-18 est disponible ici : schema-2021-03-18.zip

Lambda génère le message de journal platform.runtimeDone quand le runtime envoie une demande d'API de runtime Next ou Error. Le journal platform.runtimeDone informe les utilisateurs de l'API Logs que l'appel de fonction se termine. Les extensions peuvent utiliser ces informations pour décider quand envoyer toutes les données télémétriques collectées au cours de cet appel.

Exemples

Lambda envoie le message platform.runtimeDone après que le runtime a envoyé la demande NEXT à l'issue de l'appel de fonction. Les exemples suivants présentent des messages pour chacune des valeurs de statut : succès, échec et expiration du délai.

Exemple de message de réussite

{
    "time": "2021-02-04T20:00:05.123Z",
    "type": "platform.runtimeDone",
    "record": {
       "requestId":"6f7f0961f83442118a7af6fe80b88",
       "status": "success"
    }
}         

Exemple de message d'échec

{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "failure"
   }
}        

Exemple de message d'expiration du délai

{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "timeout"
  }
}

Exemple de plateforme. restoreRuntimeDone message (type snap-start d'initialisation uniquement)

La plateforme. restoreRuntimeDoneun message de journal indique si la Restore phase a réussi ou non. Lambda envoie ce message lorsque l'environnement d'exécution envoie une demande d'API d'exécution restore/next. Il existe trois statuts possibles : succès, échec et dépassement de délai. L'exemple suivant montre une plateforme performante. restoreRuntimeDonemessage de journal.

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