Journalisation et surveillance des fonctions Lambda C#

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 avec Lambda.

Création d’une fonction qui renvoie des journaux

Pour générer des journaux à partir de votre code de fonction, vous pouvez utiliser le ILambdaLogger sur l'objet de contexte, les méthodes de la classe Console ou toute bibliothèque de journalisation qui écrit dans stdout oustderr.

L’environnement d’exécution .NET 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 .NET

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 .NET 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 Lambda .NET, consultez les instructions des sections suivantes.

Utilisation du format de journal JSON structuré avec .NET

Si vous sélectionnez JSON pour le format de journal de votre fonction, Lambda enverra les journaux en sortie à l'aide de ILambdaLogger sous forme de JSON structuré. Chaque objet de journal JSON contient au moins cinq paires clé-valeur avec les clés suivantes :

L’instance ILambdaLogger peut ajouter des paires clé-valeur supplémentaires, par exemple lors de la journalisation des exceptions. Vous pouvez également fournir vos propres paramètres supplémentaires, comme décrit dans la section Paramètres de journal fournis par le client.

L’exemple de commande de journalisation suivant montre comment écrire un message de journal de niveau INFO.

context.Logger.LogInformation("Fetching cart from database");

Vous pouvez également utiliser une méthode de journal générique qui prend le niveau de journal comme argument, comme le montre l’exemple suivant.

context.Logger.Log(LogLevel.Information, "Fetching cart from database");

La sortie du journal par ces exemples d'extraits de code serait capturée dans CloudWatch Logs comme suit :

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Fetching cart from database"
}

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

Exceptions de journalisation au format JSON

Lorsque vous utilisez la journalisation JSON structurée avec ILambdaLogger, vous pouvez journaliser les exceptions dans votre code, comme indiqué dans l’exemple suivant.

try
{
    connection.ExecuteQuery(query);
}
catch(Exception e)
{
    context.Logger.LogWarning(e, "Error executing query");
}

Le format de journal généré par ce code est illustré dans l’exemple de JSON suivant. Notez que la propriété message du JSON est renseignée à l’aide de l’argument message fourni dans l’appel LogWarning, tandis que la propriété errorMessage provient de la propriété Message de l’exception elle-même.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Warning",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Error executing query",
    "errorType": "System.Data.SqlClient.SqlException",
    "errorMessage": "Connection closed",
    "stackTrace": ["<call exception.StackTrace>"]
}

Si le format de journalisation de votre fonction est défini sur JSON, Lambda produit également des messages de journal au format JSON lorsque votre code génère une exception non détectée. L’exemple d’extrait de code et de message de journal suivants montre comment les exceptions non détectées sont journalisées.

throw new ApplicationException("Invalid data");

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Error",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Invalid data",
    "errorType": "System.ApplicationException",
    "errorMessage": "Invalid data",
    "stackTrace": ["<call exception.StackTrace>"]
}

Paramètres de journal fournis par le client

Avec les messages de journal au format JSON, vous pouvez fournir des paramètres de journal supplémentaires et les inclure dans le journal message. L’exemple d’extrait de code suivant montre une commande permettant d’ajouter deux paramètres fournis par l’utilisateur et étiquetés retryAttempt et uri. Dans l’exemple, la valeur de ces paramètres provient des arguments retryAttempt et uriDestination transmis à la commande de journalisation.

context.Logger.LogInformation("Starting retry {retryAttempt} to make GET request to {uri}", retryAttempt, uriDestination);

Le message du journal généré par cette commande est illustré dans l’exemple de fichier JSON suivant.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Starting retry 1 to make GET request to http://example.com/",
    "retryAttempt": 1,
    "uri": "http://example.com/"
}

context.Logger.LogInformation("Starting retry {0} to make GET request to {1}", retryAttempt, uriDestination);

Notez que lorsque vous fournissez des paramètres de journalisation supplémentaires, Lambda les capture en tant que propriétés de premier niveau dans l’enregistrement de journal JSON. Cette approche diffère de certaines bibliothèques de journalisation .NET populaires Serilog, telles que celles qui capturent des paramètres supplémentaires dans un objet enfant distinct.

Si l’argument que vous fournissez pour un paramètre supplémentaire est un objet complexe, Lambda utilise par défaut la méthode ToString() pour fournir la valeur. Pour indiquer qu’un argument doit être sérialisé au format JSON, utilisez le préfixe @ tel qu’illustré dans l’extrait de code suivant. Dans cet exemple, User est un objet doté de propriétés FirstName et LastName.

context.Logger.LogInformation("User {@user} logged in", User);

Le message du journal généré par cette commande est illustré dans l’exemple de fichier JSON suivant.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "User {@user} logged in",
    "user": 
    {
        "FirstName": "John",
        "LastName": "Doe"
    }
}

Si l’argument d’un paramètre supplémentaire est un tableau ou implémente IList ou IDictionary, alors Lambda ajoute l’argument au message de journal JSON sous forme de tableau, comme indiqué dans l’exemple d’enregistrement de journal JSON suivant. Dans cet exemple, {users} prend un argument IList contenant des instances de la propriété User au même format que dans l’exemple précédent. Lambda le convertit cet IList en tableau, chaque valeur étant créée à l’aide de la méthode ToString.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "{users} have joined the group",
    "users": 
    [
        "Rosalez, Alejandro",
        "Stiles, John"       
    ] 
}

Vous pouvez également sérialiser la liste au format JSON en utilisant le préfixe @ dans votre commande de journalisation. Dans l’exemple d’enregistrement de journal JSON suivant, la propriété users est sérialisée au format JSON.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "{@users} have joined the group",
    "users": 
    [
        {
            "FirstName": "Alejandro",
            "LastName": "Rosalez"
        },
        {
            "FirstName": "John",
            "LastName": "Stiles"
        }        
    ] 
}

Utilisation du filtrage au niveau du journal avec .NET

En configurant le filtrage au niveau des journaux, vous pouvez choisir de n'envoyer que les journaux d'un certain niveau de détail ou inférieur à CloudWatch Logs. Pour savoir comment configurer le filtrage de niveau journal de votre fonction, consultez Filtrage au niveau du journal.

AWS Lambda Pour filtrer vos messages de journal par niveau de journal, vous pouvez soit utiliser des journaux au format JSON, soit utiliser les Console méthodes .NET pour générer des messages de journal. Pour créer des journaux au format JSON, configurez le type de journal de votre fonction sur JSON et utilisez l’instance ILambdaLogger.

Avec les journaux formatés en JSON, Lambda filtre les sorties de votre journal à l’aide de la paire clé-valeur « niveau » de l’objet JSON décrit dans Utilisation du format de journal JSON structuré avec .NET.

Si vous utilisez les Console méthodes .NET pour écrire des messages dans CloudWatch Logs, Lambda applique les niveaux de journalisation à vos messages comme suit :

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 Notez le mappage des niveaux de journalisation utilisés par Lambda avec les niveaux Microsoft standard utilisés par l’attribut .NET ILambdaLogger.

Lambda envoie des journaux correspondant au niveau de détail 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.

Outils de journalisation et bibliothèques supplémentaires

Powertools for AWS Lambda (.NET) 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 (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 (.NET) 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 C# avec des modules Powertools pour AWS Lambda (.NET) 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 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

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.

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