Enregistrez et surveillez les fonctions Java Lambda

AWS Lambda surveille automatiquement les fonctions Lambda et envoie des entrées de journal à Amazon. CloudWatch Votre fonction Lambda est fournie avec un groupe de CloudWatch journaux 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 plus d'informations sur CloudWatch les journaux, consultezUtilisation des CloudWatch journaux et journaux 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 aws-lambda-java-corebibliothèque fournit une classe d'enregistreur nommée à LambdaLogger laquelle vous pouvez accéder depuis 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 d'un format de JSON journal structuré avec Java

Si vous sélectionnez le JSON format de journal de votre fonction, Lambda enverra les journaux en utilisant la LambdaLogger classe telle que structurée. JSON Chaque objet JSON journal 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 JSON format 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);

Cette sortie de journal produite par cet exemple de code serait capturée 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 journalisation pour produire des journaux JSON structurés, vous n'avez aucune modification à apporter. Lambda ne double code aucun journal déjà codé. JSON Même si vous configurez votre fonction pour utiliser le format JSON journal, vos sorties de journalisation apparaissent CloudWatch dans la JSON structure que vous définissez.

Utilisation du filtrage au niveau du journal avec Java

AWS Lambda Pour filtrer les journaux de vos applications en fonction de leur niveau de journalisation, votre fonction doit utiliser des journaux JSON formatés. 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 à Logs : 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 JSON journal. L'heure doit être spécifiée dans un format d'horodatage RFC3339 valide. Si vous ne fournissez pas d'horodatage valide, Lambda attribuera le niveau au journal INFO et ajoutera un horodatage pour vous.

Lambda envoie les journaux du niveau sélectionné et d'un niveau inférieur à. CloudWatch Par exemple, si vous configurez un niveau de journalisation deWARN, Lambda enverra des journaux correspondant aux niveaux WARNERROR, etFATAL.

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 AWS SDK appels, 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. SLF4Jest une bibliothèque de façade qui vous permet de changer la bibliothèque que vous utilisez sans changer le code de votre fonction.

Pour ajouter l'ID de demande aux journaux de votre fonction, utilisez l'annexe de 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 le texte brut ou pour les JSON sorties en spécifiant une mise en page sous les <LambdaTextFormat> balises 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 JSON mode, le <JsonTemplateLayout> est utilisé avec une configuration fournie avec la aws-lambda-java-log4j2 bibliothèque.

SLF4Jest une bibliothèque de façade permettant de se connecter en code Java. Dans votre code de fonction, vous utilisez l'usine d'enregistrement pour récupérer un SLF4J enregistreur avec des méthodes pour les niveaux de journalisation telles que info() et. warn() Dans votre configuration de compilation, vous incluez la bibliothèque de journalisation et l'SLF4Jadaptateur 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. SLF4Jest nécessaire pour capturer les journaux SDK depuis 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 construction prend en compte les dépendances d'exécution sur l'appendice et l'SLF4Jadaptateur Lambda, ainsi que les 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'accroître la rapidité des développeurs. L'utilitaire Logging fournit un enregistreur optimisé pour Lambda qui inclut des informations supplémentaires sur le contexte des fonctions dans toutes vos fonctions avec une sortie structurée comme suit. 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 Java Hello World avec des modules Powertools for AWS Lambda (Java) ~ intégrés à l'aide du AWS SAM. Cette application implémente un API backend de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Il se compose d'un point de terminaison Amazon API Gateway et d'une fonction Lambda. Lorsque vous envoyez une GET demande au point de terminaison API Gateway, la fonction Lambda appelle, 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 CloudWatch sont automatiquement supprimés. Pour configurer la conservation des journaux, ajoutez ce qui suit à 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

Afficher les 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.

Afficher les 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 traiter plusieurs invocations simultanées. Pour trouver les journaux d'un appel spécifique, nous vous recommandons d'instrumenter votre fonction avec. AWS X-Ray X-Ray enregistre des détails sur la demande et le flux de journaux dans le suivi.

Afficher les journaux à l'aide de AWS Command Line Interface (AWS CLI)

AWS CLI Il s'agit d'un outil open source qui vous permet d'interagir avec les AWS services à l'aide de commandes dans votre interface de ligne de commande. Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :

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 inclut des exemples d'applications illustrant 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 est utilisé SLF4J comme façade pour assurer la compatibilité avec le AWS SDK. Les bibliothèques de journalisation sont exclues de la sortie de build pour limiter la taille du package de déploiement.