Journalisation et surveillance des fonctions Lambda Java

AWS Lambda surveille automatiquement les fonctions Lambda et envoie les entrées de journal à Amazon CloudWatch. Votre fonction Lambda est fournie avec un groupe de CloudWatch journaux 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 plus d'informations sur CloudWatch les journaux, consultezEnvoi des journaux des fonctions Lambda à CloudWatch Logs.

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: 724 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 façon 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 commandes de journalisation avancées pour votre fonction 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 la sortie des journaux en utilisant la LambdaLogger classe 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 attribue automatiquement le niveau INFO.

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

Utilisation du filtrage au niveau du journal avec Java

AWS Lambda Pour filtrer 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 aux journaux : CloudWatch

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 attribue au journal le niveau INFO et vous ajoute un horodatage.

Lambda envoie les journaux du niveau sélectionné et 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 lors des tests unitaires et enregistrer les appels au AWS SDK, utilisez Apache Log4j2 avec SLF4J. Log4j est une bibliothèque de journalisation pour les programmes Java que vous pouvez utiliser pour configurer les niveaux de journalisation et utiliser des bibliothèques annexes. SLF4J est une bibliothèque de façade que vous pouvez utiliser pour changer la bibliothèque que vous utilisez sans modifier le code de votre 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 for AWS Lambda (Java) est une boîte à outils destinée aux développeurs qui permet de mettre en œuvre les meilleures pratiques sans serveur et d'augmenter la vitesse 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 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 for AWS Lambda (Java) intégrés à l'aide du 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 requête GET au point de terminaison API Gateway, la fonction Lambda invoque, envoie des journaux et des métriques au format métrique intégré à 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 les journaux indéfiniment, supprimez le groupe de journaux ou configurez une période de conservation après laquelle les journaux seront CloudWatch automatiquement supprimés. Pour configurer la conservation des journaux, ajoutez les éléments suivants à votre AWS SAM modèle :

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é depuis l'éditeur de code intégré, vous trouverez des journaux dans les résultats d'exécution. Lorsque vous utilisez la fonction de test de la console pour invoquer une fonction, la sortie du journal se trouve dans la section Détails.

Affichage des journaux dans la CloudWatch console

Vous pouvez utiliser la CloudWatch console Amazon pour consulter les journaux de toutes 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 gérer les appels simultanés. Pour trouver les journaux d'une invocation spécifique, nous vous recommandons d'instrumenter votre fonction avec. AWS X-Ray X-Ray enregistre les détails de la demande et du flux de log dans la trace.

Affichage des journaux à l'aide du AWS Command Line Interface (AWS CLI)

AWS CLI Il s'agit d'un outil open source que vous pouvez utiliser pour interagir avec les AWS services à 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 GitHub référentiel de ce guide comprend des exemples d'applications qui illustrent l'utilisation de différentes configurations de journalisation. Chaque exemple d'application inclut des scripts pour faciliter le déploiement et le nettoyage, un AWS SAM modèle 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 assurer la compatibilité avec le SDK. AWS Les bibliothèques de journalisation sont exclues de la sortie de build pour limiter la taille du package de déploiement.