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.
# Utilisation de l’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 vous être abonné à l'aide de l'une de ces API APIs, toute tentative de souscription à l'aide de l'autre API renvoie une erreur.
**Les instances gérées Lambda ne prennent pas en charge l'API Logs**
Les instances gérées Lambda ne prennent pas en charge l'API Logs. Si vous utilisez des fonctions d'instance gérées, utilisez plutôt l'[API de télémétrie](telemetry-api.md). L'API de télémétrie fournit des fonctionnalités améliorées pour collecter et traiter les données de télémétrie à partir de vos fonctions Lambda.
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](runtimes-extensions-api.md) peuvent utiliser l’API Lambda Runtime Logs pour s’abonner à des flux de journaux directement à partir de l’[environnement d’exécution](lambda-runtime-environment.md) 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.
![\[\]](http://docs.aws.amazon.com/fr_fr/lambda/latest/dg/images/logs-api-concept-diagram.png)
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.
**Topics**
+ [S’abonner pour recevoir des journaux](#runtimes-logs-api-subscribing)
+ [Utilisation de la mémoire](#runtimes-logs-api-memory)
+ [Protocoles de destination](#runtimes-logs-api-dest)
+ [Configuration de mise en mémoire tampon](#runtimes-logs-api-buffering)
+ [Exemple d’abonnement](#runtimes-logs-api-subs-example)
+ [Exemple de code pour l’API Logs](#runtimes-logs-api-samples)
+ [Référence d’API Logs](#runtimes-logs-api-ref)
+ [Messages de journaux](#runtimes-logs-api-msg)
## 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](runtimes-extensions-api.md#extensions-registration-api-a) pour recevoir l’identifiant de l’extension. Abonnez-vous ensuite à l’API Logs lors de [l’initialisation](lambda-runtime-environment.md#runtimes-lifecycle-ib). 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](#runtimes-logs-api-buffering). 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.
1. **TCP** – Lambda envoie les journaux à un port TCP au [format NDJSON (Newline delimited JSON)](https://github.com/ndjson/ndjson-spec).
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`. Pour de plus amples informations, veuillez consulter [Lambda : certains journaux de ma fonction n’apparaissent pas](troubleshooting-execution.md#troubleshooting-execution-missinglogs).
## 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 un exemple de code montrant comment envoyer des journaux vers une destination personnalisée, consultez la section [Utilisation d' AWS Lambda extensions pour envoyer des journaux vers des destinations personnalisées](https://aws.amazon.com/blogs/compute/using-aws-lambda-extensions-to-send-logs-to-custom-destinations/) sur le 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 Lambda Extensions](https://github.com/aws-samples/aws-lambda-extensions) dans le référentiel AWS Samples GitHub . Pour plus d’informations sur la génération d’une extension Lambda, consultez [Utilisation de l’API d’extensions Lambda pour créer des extensions](runtimes-extensions-api.md).
## 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](samples/logs-api-request.zip)
### 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](#runtimes-logs-api-dest). Obligatoire : oui. Type : chaînes.
`buffering` – Voir [Configuration de mise en mémoire tampon](#runtimes-logs-api-buffering). 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`](#runtimes-logs-api-ref-done).
****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](samples/logs-api-http-response.zip)
+ [TCP : .zip logs-api-tcp-response](samples/logs-api-tcp-response.zip)
****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.
**Topics**
+ [Journaux de fonctions](#runtimes-logs-api-msg-function)
+ [Journaux d’extension](#runtimes-logs-api-msg-extension)
+ [Journaux de plateforme](#runtimes-logs-api-msg-platform)
### 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. \$1 "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\$1n\$1my-function (line 10)\$1n" \$1
### 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. initRuntimeDone**un message de journal indique l'état de la `Runtime init` sous-phase, qui fait partie de la phase du cycle de [vie d'initialisation](lambda-runtime-environment.md#runtimes-lifecycle-ib). 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. initRuntimeDone**message 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"
}
```
**Note**
AWS met actuellement en œuvre des modifications du service Lambda. En raison de ces modifications, vous pouvez constater des différences mineures entre la structure et le contenu des messages du journal système et des segments de suivi émis par les différentes fonctions Lambda de votre Compte AWS.
L’une des sorties de journal concernées par cette modification est le champ `"record"` du journal des erreurs de plateforme. Les exemples suivants montrent des champs `"record"` illustratifs dans les anciens et les nouveaux formats. Le nouveau format de journal des erreurs contient un message plus concis
Ces modifications seront mises en œuvre au cours des prochaines semaines, et toutes les fonctions, Régions AWS sauf en Chine et dans les GovCloud régions, seront transférées pour utiliser le nouveau format des messages de journal et des segments de trace.
**Example enregistrement du journal des erreurs de plateforme (ancien format)**
```
"record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError"
```
**Example enregistrement du journal des erreurs de plateforme (nouveau format)**
```
"record":"RequestId: ... Status: error\tErrorType: Runtime.ExitError"
```
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](samples/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.
**Example Exemple de message de réussite**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "success"
}
}
```
**Example Exemple de message d’échec**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "failure"
}
}
```
**Example Exemple de message d’expiration du délai**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "timeout"
}
}
```
**Example Exemple de plateforme. restoreRuntimeDone message (type `snap-start` d'initialisation uniquement)**
La **plateforme. restoreRuntimeDone**un 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. restoreRuntimeDone**message de journal.
```
{
"time":"2022-07-17T18:43:45.936Z",
"type":"platform.restoreRuntimeDone",
"record":{
"status":"success"
}
}
```