Journalisation et surveillance des fonctions Lambda Java

AWS Lambda surveille automatiquement les fonctions Lambda et envoie les entrées de journaux à Amazon CloudWatch. Votre fonction Lambda est fournie avec un groupe de journaux CloudWatch Logs et un flux de journaux pour chaque instance de votre fonction. L’environnement d’exécution Lambda envoie des détails sur chaque invocation et d’autres sorties provenant du code de votre fonction au flux de journaux. Pour de plus amples informations sur CloudWatch Logs, veuillez consulter Utilisation de CloudWatch Logs avec Lambda.

Pour produire des journaux à partir de votre code de fonction, vous pouvez utiliser des méthodes sur java.lang.System, ou tout module de journalisation qui écrit sur stdout ou stderr.

Création d’une fonction qui renvoie des journaux

Pour générer les journaux à partir de votre code de fonction, vous pouvez utiliser des méthodes sur java.lang.System ou n’importe quelle bibliothèque de journalisation qui écrit dans stdout ou stderr. La bibliothèque aws-lambda-java-core fournit une classe d’enregistreur nommée LambdaLogger à laquelle vous pouvez accéder à partir de l’objet de contexte. La classe d’enregistreur prend en charge les journaux multilignes.

L’exemple suivant utilise l’enregistreur LambdaLogger fourni par l’objet de contexte.

// Handler value: example.Handler
public class Handler implements RequestHandler<Object, String>{
  Gson gson = new GsonBuilder().setPrettyPrinting().create();
  @Override
  public String handleRequest(Object event, Context context)
  {
    LambdaLogger logger = context.getLogger();
    String response = new String("SUCCESS");
    // log execution details
    logger.log("ENVIRONMENT VARIABLES: " + gson.toJson(System.getenv()));
    logger.log("CONTEXT: " + gson.toJson(context));
    // process event
    logger.log("EVENT: " + gson.toJson(event));
    return response;
  }
}

START RequestId: 6bc28136-xmpl-4365-b021-0ce6b2e64ab0 Version: $LATEST
ENVIRONMENT VARIABLES: 
{
    "_HANDLER": "example.Handler",
    "AWS_EXECUTION_ENV": "AWS_Lambda_java8",
    "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": "512",
    ...
}
CONTEXT: 
{
    "memoryLimit": 512,
    "awsRequestId": "6bc28136-xmpl-4365-b021-0ce6b2e64ab0",
    "functionName": "java-console",
    ...
}
EVENT:
{
  "records": [
    {
      "messageId": "19dd0b57-xmpl-4ac1-bd88-01bbb068cb78",
      "receiptHandle": "MessageReceiptHandle",
      "body": "Hello from SQS!",
       ...
    }
  ]
}
END RequestId: 6bc28136-xmpl-4365-b021-0ce6b2e64ab0
REPORT RequestId: 6bc28136-xmpl-4365-b021-0ce6b2e64ab0	Duration: 198.50 ms	Billed Duration: 200 ms	Memory Size: 512 MB	Max Memory Used: 90 MB	Init Duration: 524.75 ms

L’environnement d’exécution Java enregistre les lignes START, END et REPORT pour chaque invocation. La ligne de rapport fournit les détails suivants.

Utilisation des contrôles de journalisation avancés de Lambda avec Java

Pour mieux contrôler la manière dont les journaux de vos fonctions sont capturés, traités et consommés, vous pouvez configurer les options de journalisation suivantes pour les environnements d’exécution Java pris en charge :

Pour plus d’informations sur ces options de journalisation et pour savoir comment configurer votre fonction pour les utiliser, consultez Configuration de contrôles de journalisation avancés pour les fonctions Lambda.

Pour utiliser le format de journal et les options de niveau de journal avec vos fonctions Java Lambda, consultez les instructions des sections suivantes.

Utilisation du format de journal JSON structuré avec Java

Si vous sélectionnez JSON pour le format de journal de votre fonction, Lambda envoie les journaux en utilisant la classe LambdaLogger sous forme de JSON structuré. Chaque objet de journal JSON contient au moins quatre paires clé-valeur avec les clés suivantes :

Selon la méthode de journalisation que vous utilisez, les sorties de journal de votre fonction capturées au format JSON peuvent également contenir des paires clé-valeur supplémentaires.

Pour attribuer un niveau aux journaux que vous créez à l’aide de l’enregistreur LambdaLogger, vous devez fournir un argument LogLevel dans votre commande de journalisation, comme illustré dans l’exemple suivant.

LambdaLogger logger = context.getLogger();
logger.log("This is a debug log", LogLevel.DEBUG);

Ce journal généré par cet exemple de code serait capturé dans CloudWatch Logs comme suit :

{
    "timestamp":"2023-11-01T00:21:51.358Z",
    "level":"DEBUG",
    "message":"This is a debug log",
    "AWSrequestId":"93f25699-2cbf-4976-8f94-336a0aa98c6f"
}

Si vous n’attribuez aucun niveau à la sortie de votre journal, Lambda lui attribuera automatiquement le niveau INFO.

Si votre code utilise déjà une autre bibliothèque de journaux pour produire des journaux structurés JSON, vous n’avez pas besoin d’apporter de modifications. Lambda ne double code aucun journal déjà codé au format JSON. Même si vous configurez votre fonction pour utiliser le format de journal JSON, vos résultats de journalisation apparaissent dans CloudWatch dans la structure JSON que vous définissez.

Utilisation du filtrage au niveau du journal avec Java

Pour qu’AWS Lambda filtre les journaux de votre application en fonction de leur niveau de journalisation, votre fonction doit utiliser des journaux au format JSON. Vous pouvez effectuer cette opération de deux façons :

Lorsque vous configurez votre fonction pour utiliser le filtrage au niveau des journaux, vous devez sélectionner l’une des options suivantes pour le niveau de journaux que Lambda doit envoyer à CloudWatch Logs :

Pour que Lambda puisse filtrer les journaux de votre fonction, vous devez également inclure une paire "timestamp" clé-valeur dans la sortie de votre journal JSON. L'heure doit être spécifiée dans un format d'horodatage RFC 3339 valide. Si vous ne fournissez pas d’horodatage valide, Lambda attribuera au journal le niveau INFO et ajoutera un horodatage pour vous.

Lambda envoie des journaux du niveau sélectionné ou inférieur à CloudWatch. Par exemple, si vous configurez un niveau de journalisation WARN, Lambda envoie des journaux correspondant aux niveaux WARN, ERROR et FATAL.

Implémentation de la journalisation avancée avec Log4j2 et SLF4J

Pour personnaliser la sortie du journal, prendre en charge la journalisation pendant les tests unitaires et enregistrer les appels du kit SDK AWS, utilisez Apache Log4j2 avec SLF4J. Log4j est une bibliothèque de journalisation pour les programmes Java qui vous permet de configurer les niveaux de journalisation et d’utiliser les bibliothèques appender. SLF4J est une bibliothèque de façade qui vous permet de changer la bibliothèque que vous utilisez sans modifier votre code de fonction.

Pour ajouter l’ID de requête aux journaux de votre fonction, utilisez l’appender dans la bibliothèque aws-lambda-java-log4j2.

<Configuration>
  <Appenders>
    <Lambda name="Lambda" format="${env:AWS_LAMBDA_LOG_FORMAT:-TEXT}">
       <LambdaTextFormat>
         <PatternLayout>
             <pattern>%d{yyyy-MM-dd HH:mm:ss} %X{AWSRequestId} %-5p %c{1} - %m%n </pattern>
         </PatternLayout>
       </LambdaTextFormat>
       <LambdaJSONFormat>
         <JsonTemplateLayout eventTemplateUri="classpath:LambdaLayout.json" />
       </LambdaJSONFormat>
     </Lambda>
   </Appenders>
   <Loggers>
     <Root level="${env:AWS_LAMBDA_LOG_LEVEL:-INFO}">
       <AppenderRef ref="Lambda"/>
     </Root>
     <Logger name="software.amazon.awssdk" level="WARN" />
     <Logger name="software.amazon.awssdk.request" level="DEBUG" />
   </Loggers>
 </Configuration>

Vous pouvez décider comment vos journaux Log4j2 sont configurés pour les sorties en texte brut ou JSON en spécifiant une mise en page sous les balises <LambdaTextFormat> et <LambdaJSONFormat>.

Dans cet exemple, en mode texte, chaque ligne est précédée de la date, de l’heure, de l’ID de demande, du niveau de journal et du nom de classe. En mode JSON, <JsonTemplateLayout> est utilisé avec une configuration fournie avec la bibliothèque aws-lambda-java-log4j2.

SLF4J est une bibliothèque de façade pour la journalisation en code Java. Dans votre code de fonction, vous utilisez la fabrique d’enregistreurs SLF4J pour récupérer un enregistreur avec des méthodes pour les niveaux de journalisation comme info() et warn(). Dans votre configuration de build, vous incluez la bibliothèque de journalisation et l’adaptateur SLF4J dans le chemin de classe. En changeant les bibliothèques dans la configuration de build, vous pouvez changer le type d’enregistreur sans changer votre code de fonction. SLF4J est nécessaire pour capturer les journaux du kit SDK pour Java.

Dans l’exemple de code suivant, la classe de gestionnaire utilise SLF4J pour récupérer un enregistreur.

package example;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.events.S3Event;

import static org.apache.logging.log4j.CloseableThreadContext.put;


public class HandlerS3 implements RequestHandler<S3Event, String>{
    private static final Logger logger = LoggerFactory.getLogger(HandlerS3.class);

    @Override
    public String handleRequest(S3Event event, Context context) {
        for(var record : event.getRecords()) {
            try (var loggingCtx = put("awsRegion", record.getAwsRegion())) {
                loggingCtx.put("eventName", record.getEventName());
                loggingCtx.put("bucket", record.getS3().getBucket().getName());
                loggingCtx.put("key", record.getS3().getObject().getKey());

                logger.info("Handling s3 event");
            }
        }

        return "Ok";
    }
}

Ce code produit des sorties de journal similaires à ce qui suit  :

{
    "timestamp": "2023-11-15T16:56:00.815Z",
    "level": "INFO",
    "message": "Handling s3 event",
    "logger": "example.HandlerS3",
    "AWSRequestId": "0bced576-3936-4e5a-9dcd-db9477b77f97",
    "awsRegion": "eu-south-1",
    "bucket": "java-logging-test-input-bucket",
    "eventName": "ObjectCreated:Put",
    "key": "test-folder/"
}

La configuration de build prend des dépendances d’exécution sur l’appender Lambda et l’adaptateur SLF4J, et des dépendances d’implémentation sur Log4j2.

dependencies {
    ...
    'com.amazonaws:aws-lambda-java-log4j2:[1.6.0,)',
    'com.amazonaws:aws-lambda-java-events:[3.11.3,)',
    'org.apache.logging.log4j:log4j-layout-template-json:[2.17.1,)',
    'org.apache.logging.log4j:log4j-slf4j2-impl:[2.19.0,)',
    ...
}

Lorsque vous exécutez votre code localement pour des tests, l’objet contecte avec l’enregistreur Lambda n’est pas disponible, et il n’y a pas d’ID de requête que l’appender Lambda puisse utiliser. Pour des exemples de configurations de test, consultez les exemples d’applications dans la section suivante.

Utilisation d’autres outils et bibliothèques de journalisation

Powertools pour AWS Lambda (Java) est une boîte à outils pour développeurs permettant de mettre en œuvre les bonnes pratiques en matière de sans serveur et d’augmenter la rapidité des développeurs. L’utilitaire Logging (français non garanti) fournit un enregistreur optimisé pour Lambda qui inclut des informations supplémentaires sur le contexte de fonction pour toutes vos fonctions avec une sortie structurée en JSON. Utilisez cet utilitaire pour effectuer les opérations suivantes :

Utilisation de Powertools pour AWS Lambda (Java) et de AWS SAM pour la journalisation structurée

Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d’application Hello World Java avec des modules Powertools pour AWS Lambda (Java) ~ intégrés à l’aide de AWS SAM. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une demande GET au point de terminaison API Gateway, la fonction Lambda est invoquée, envoie des journaux et des métriques à l’aide du format Embedded Metric à CloudWatch, et envoie des traces à AWS X-Ray. La fonction renvoie un message hello world.

Gestion de la conservation des journaux

Les groupes de journaux ne sont pas supprimés automatiquement quand vous supprimez une fonction. Pour éviter de stocker des journaux indéfiniment, supprimez le groupe de journaux ou configurez une période de conservation à l’issue de laquelle CloudWatch supprime automatiquement les journaux. Pour configurer la conservation des journaux, ajoutez les éléments suivants à votre modèle AWS SAM :

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      # Omitting other properties

  LogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
      RetentionInDays: 7

Affichage des journaux dans la console Lambda

Vous pouvez utiliser la console Lambda pour afficher la sortie du journal après avoir invoqué une fonction Lambda.

Si votre code peut être testé à partir de l’éditeur Code intégré, vous trouverez les journaux dans les résultats d’exécution. Lorsque vous utilisez la fonctionnalité de test de console pour invoquer une fonction, vous trouverez Sortie du journal dans la section Détails.

Affichage des journaux dans la console CloudWatch

Vous pouvez utiliser la console Amazon CloudWatch pour afficher les journaux de tous les invocations de fonctions Lambda.

Chaque flux de journal correspond à une instance de votre fonction. Un flux de journaux apparaît lorsque vous mettez à jour votre fonction Lambda et lorsque des instances supplémentaires sont créées pour traiter plusieurs invocations simultanées. Pour trouver des journaux pour une invocation spécifique, nous vous recommandons d’utiliser votre fonction avec AWS X-Ray. X-Ray enregistre des détails sur la demande et le flux de journaux dans le suivi.

Affichage des journaux à l’aide de l’AWS Command Line Interface (AWS CLI)

La AWS CLI est un outil open-source qui vous permet d’interagir avec des services AWS à l’aide des commandes de votre shell de ligne de commande. Pour effectuer les étapes de cette section, vous devez disposer de la version 2 de l’AWS CLI.

Vous pouvez utiliser AWS CLI pour récupérer les journaux d’une invocation à l’aide de l’option de commande --log-type. La réponse inclut un champ LogResult qui contient jusqu’à 4 Ko de journaux codés en base64 provenant de l’invocation.

aws lambda invoke --function-name my-function out --log-type Tail

{
    "StatusCode": 200,
    "LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
    "ExecutedVersion": "$LATEST"
}

aws lambda invoke --function-name my-function out --log-type Tail \
--query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode

START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST
"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8
REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8  Duration: 79.67 ms      Billed Duration: 80 ms         Memory Size: 128 MB     Max Memory Used: 73 MB

#!/bin/bash
aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out
sed -i'' -e 's/"//g' out
sleep 15
aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5

chmod -R 755 get-logs.sh

./get-logs.sh

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}
{
    "events": [
        {
            "timestamp": 1559763003171,
            "message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n",
            "ingestionTime": 1559763003309
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r  \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r  \"key\": \"value\"\r}\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n",
            "ingestionTime": 1559763018353
        }
    ],
    "nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795",
    "nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080"
}

Suppression de journaux

Les groupes de journaux ne sont pas supprimés automatiquement quand vous supprimez une fonction. Pour éviter de stocker des journaux indéfiniment, supprimez le groupe de journaux ou configurez une période de conservation à l’issue de laquelle les journaux sont supprimés automatiquement.

Exemple de code de journalisation

Le référentiel GitHub de ce guide comprend des exemples d’applications qui démontrent l’utilisation de diverses configurations de journalisation. Chaque exemple d’application inclut des scripts facilitant le déploiement et le nettoyage, un modèle AWS SAM et des ressources de support.

L’exemple java-basic d’application présente une configuration de journalisation minimale qui prend en charge les tests de journalisation. Le code du gestionnaire utilise l’enregistreur LambdaLogger fourni par l’objet de contexte. Pour les tests, l’application utilise une classe TestLogger personnalisée qui implémente l’interface LambdaLogger avec un logger Log4j2. Il utilise SLF4J comme façade pour la compatibilité avec le kit SDK AWS. Les bibliothèques de journalisation sont exclues de la sortie de build pour limiter la taille du package de déploiement.