Journalisation et surveillance des fonctions Lambda Ruby

AWS Lambda surveille automatiquement les fonctions Lambda en votre nom et envoie les journaux à 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 informations sur chaque invocation au flux de journaux et transmet les journaux et autres sorties provenant du code de votre fonction. Pour de plus amples informations, veuillez consulter Envoi automatique des journaux de la fonction Lambda à CloudWatch Logs.

Cette page explique comment générer une sortie de journal à partir du code de votre fonction Lambda et comment accéder aux journaux à l'aide de la AWS Command Line Interface console Lambda ou de la console. CloudWatch

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 déclarations puts ou n’importe quelle bibliothèque de journalisation qui écrit dans stdout ou stderr. L’exemple suivant consigne les valeurs des variables d’environnement et l’objet d’événement.

# lambda_function.rb

def handler(event:, context:)
    puts "## ENVIRONMENT VARIABLES"
    puts ENV.to_a
    puts "## EVENT"
    puts event.to_a
end

START RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Version: $LATEST
## ENVIRONMENT VARIABLES
environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]3893xmpl7fac4485b47bb75b671a283c', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...})
## EVENT
{'key': 'value'}
END RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95
REPORT RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95  Duration: 15.74 ms  Billed Duration: 147 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 130.49 ms
XRAY TraceId: 1-5e34a614-10bdxmplf1fb44f07bc535a1   SegmentId: 07f5xmpl2d1f6f85 Sampled: true   

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

Pour obtenir des journaux plus détaillés, utilisez la bibliothèque Utilisation de la bibliothèque Ruby logger.

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

Pour vous permettre de mieux contrôler la manière dont les journaux de vos fonctions sont capturés, traités et consommés, Lambda propose des contrôles de journalisation avancés avec Ruby. Pour les environnements d'exécution de Ruby 4.0 et versions ultérieures, vous pouvez configurer les options de journalisation suivantes :

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 en savoir plus sur l'utilisation du format de journal et des options de niveau de journal avec vos fonctions Ruby Lambda, consultez les instructions des sections suivantes.

Utilisation de journaux JSON structurés avec Ruby

Si vous sélectionnez JSON pour le format de journal de votre fonction, Lambda enverra les journaux produits par la Logger bibliothèque standard Ruby au CloudWatch format JSON structuré. Chaque objet de journal JSON contient au moins quatre paires clé-valeur avec les clés suivantes :

La Logger bibliothèque Ruby peut également ajouter des paires clé-valeur supplémentaires, comme dans "logger" cet objet JSON.

Les exemples présentés dans les sections suivantes montrent comment les sorties de journal générées à l'aide de la Logger bibliothèque Ruby sont capturées dans CloudWatch Logs lorsque vous configurez le format de journal de votre fonction au format JSON.

Notez que si vous utilisez la puts méthode pour produire des sorties de journal de base comme décrit dansCréation d’une fonction qui renvoie des journaux, Lambda capturera ces sorties sous forme de texte brut, même si vous configurez le format de journalisation de votre fonction au format JSON.

Sorties de journal JSON standard à l'aide de la bibliothèque Ruby Logger

Les exemples d'extrait de code et de sortie de journal suivants montrent comment les sorties de journal standard générées à l'aide de la Logger bibliothèque Ruby sont capturées dans CloudWatch Logs lorsque le format de journal de votre fonction est défini sur JSON.

require 'logger'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  logger.info("Inside the handler function")
end

{
    "timestamp": "2025-10-27T19:17:45.586Z",
    "level": "INFO",
    "message": "Inside the handler function",
    "requestId": "79b4f56e-95b1-4643-9700-2807f4e68189"
}

Enregistrement de paramètres supplémentaires au format JSON

Lorsque le format de journal de votre fonction est défini sur JSON, vous pouvez également enregistrer des paramètres supplémentaires avec la Logger bibliothèque Ruby en transmettant un hachage de paires clé-valeur supplémentaires à la sortie du journal.

require 'logger'
require 'json'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  extra_params = { "a" => "b", "b" => [3] }
  logger.info({ message: "extra parameters example" }.merge(extra_params).to_json)
end

{
    "timestamp": "2025-11-02T15:26:28Z",
    "level": "INFO",
    "message": "extra parameters example",
    "requestId": "3dbd5759-65f6-45f8-8d7d-5bdc79a3bd01",
    "a": "b",
    "b": [
        3
    ]
}

Exceptions de journalisation au format JSON

L'extrait de code suivant montre comment les exceptions Ruby sont capturées dans la sortie du journal de votre fonction lorsque vous configurez le format de journal au format JSON. Notez que les sorties de journal générées à l'logger.erroraide d'une exception se voient attribuer le niveau de journal ERROR.

require 'logger'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  begin
    raise "exception"
  rescue => e
    logger.error(e)
  end
end

{
    "timestamp": "2025-11-02T16:18:57Z",
    "level": "ERROR",
    "message": "exception",
    "stackTrace": [
        "  /var/task/lambda_function.rb:4:in `lambda_handler'"
    ],
    "errorType": "RuntimeError",
    "errorMessage": "exception",
    "requestId": "3f9d155c-0f09-46b7-bdf1-e91dab220855",
    "location": "/var/task/lambda_function.rb:lambda_handler:6"
}

Utilisation du filtrage au niveau du journal avec Ruby

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

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 :

Vous pouvez également utiliser une puts instruction pour générer un objet JSON contenant un identifiant de niveau de journalisation. L'putsinstruction suivante produit une sortie au format JSON dans laquelle le niveau de journalisation est défini sur INFO. AWS Lambda enverra l'objet JSON à CloudWatch Logs si le niveau de journalisation de votre fonction est défini sur INFO, DEBUG ou TRACE.

puts '{"msg":"My log message", "level":"info"}'

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.

Utilisation d'une autre bibliothèque de journalisation

Si vous devez utiliser une version personnalisée de la logger bibliothèque, vous pouvez l'inclure dans votre package de déploiement ou dans une couche Lambda, et définir la variable d'RUBYLIBenvironnement sur le répertoire de lib la bibliothèque. Le moteur d'exécution Lambda chargera votre version au lieu de celle fournie.

Si votre code utilise déjà une autre bibliothèque de journalisation pour produire des journaux structurés en JSON, vous n'avez aucune modification à apporter. AWS 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 sorties de journalisation apparaissent CloudWatch dans la structure JSON que vous définissez.

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 journal 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'un appel 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 le traçage.

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.

Utilisation de la bibliothèque Ruby logger

La bibliothèque Ruby logger renvoie des journaux simplifiés, faciles à lire. Utilisez l’utilitaire logger pour obtenir des informations détaillées, des messages et des codes d’erreur relatifs à votre fonction.

# lambda_function.rb

require 'logger'

def handler(event:, context:) 
  logger = Logger.new($stdout)
  logger.info('## ENVIRONMENT VARIABLES')
  logger.info(ENV.to_a)
  logger.info('## EVENT')
  logger.info(event)
  event.to_a
end

La sortie de logger inclut le niveau de journal, l’horodatage et l’ID de demande.

START RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 Version: $LATEST
[INFO]  2020-01-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## ENVIRONMENT VARIABLES

[INFO]  2020-01-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]1bbe51xmplb34a2788dbaa7433b0aa4d', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...})

[INFO]  2020-01-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## EVENT

[INFO]  2020-01-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    {'key': 'value'}

END RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125
REPORT RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125  Duration: 2.75 ms   Billed Duration: 117 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 113.51 ms
XRAY TraceId: 1-5e34a66a-474xmpl7c2534a87870b4370   SegmentId: 073cxmpl3e442861 Sampled: true