Instrumentation du code Ruby dans AWS Lambda

Lambda s'intègre AWS X-Ray à pour vous permettre de tracer, de déboguer et d'optimiser les applications Lambda. Vous pouvez utiliser X-Ray pour suivre une demande lorsqu'elle qu'elle parcourt les ressources de votre application, de l'API frontale au stockage et à la base de données sur le backend. En ajoutant simplement la bibliothèque X-Ray SDK à votre configuration de build, vous pouvez enregistrer les erreurs et la latence pour tout appel que votre fonction effectue à un AWS service.

Une fois que vous avez configuré le suivi actif, vous pouvez observer des demandes spécifiques via votre application. Le graphique des X-Ray services présente des informations sur votre application et tous ses composants. L’exemple suivant montre une application dotée de deux fonctions. La fonction principale traite les événements et renvoie parfois des erreurs. La deuxième fonction en haut de la page traite les erreurs qui apparaissent dans le groupe de journaux de la première et utilise le AWS SDK pour appeler X-Ray Amazon Simple Storage Service (Amazon S3) et Amazon CloudWatch Logs.

Pour activer/désactiver le traçage actif sur votre fonction Lambda avec la console, procédez comme suit :

Votre fonction a besoin d'une autorisation pour télécharger des données de suivi vers X-Ray. Lorsque vous activez le suivi actif dans la console Lambda, Lambda ajoute les autorisations requises au rôle d’exécution de votre fonction. Sinon, ajoutez la AWSXRayDaemonWriteAccess politique au rôle d'exécution.

X-Ray ne retrace pas toutes les demandes jusqu'à votre application. X-Ray applique un algorithme d'échantillonnage pour garantir l'efficacité du traçage, tout en fournissant un échantillon représentatif de toutes les demandes. Le taux d’échantillonnage est 1 demande par seconde et 5 % de demandes supplémentaires. Vous ne pouvez pas configurer la fréquence X-Ray d'échantillonnage pour vos fonctions.

Dans X-Ray, une trace enregistre des informations relatives à une demande traitée par un ou plusieurs services. Lambda enregistre deux segments par suivi, ce qui a pour effet de créer deux nœuds sur le graphique du service. L’image suivante met en évidence ces deux nœuds :

Le premier nœud sur la gauche représente le service Lambda qui reçoit la demande d’invocation. Le deuxième nœud représente votre fonction Lambda spécifique. L’exemple suivant illustre une trace avec ces deux segments. Les deux sont nommés my-function, mais l’un a pour origine AWS::Lambda et l’autre a pour origine AWS::Lambda::Function. Si le segment AWS::Lambda affiche une erreur, cela signifie que le service Lambda a rencontré un problème. Si le segment AWS::Lambda::Function affiche une erreur, cela signifie que votre fonction a rencontré un problème.

Cet exemple développe le segment AWS::Lambda::Function pour afficher ses trois sous-segments.

Le segment de fonction à l’ancienne contient les sous-segments suivants :

Le segment de fonction de style moderne ne contient pas de sous-segment Invocation. À la place, les sous-segments du client sont directement rattachés au segment de fonction. Pour plus d’informations sur la structure des segments de fonction à l’ancienne et de style moderne, consultez Comprendre les X-Ray traces.

Vous pouvez instrumenter le code de gestionnaire pour enregistrer les métadonnées et suivre les appels en aval. Pour enregistrer les détails des appels que votre gestionnaire passe vers d'autres ressources et services, utilisez le X-Ray SDK pour Ruby. Pour obtenir ce kit SDK, ajoutez le package aws-xray-sdk aux dépendances de votre application.

# Gemfile
source 'https://rubygems.org'

gem 'aws-xray-sdk', '0.11.4'
gem 'aws-sdk-lambda', '1.39.0'
gem 'test-unit', '3.3.5'

Pour instrumenter les clients du AWS SDK, demandez le aws-xray-sdk/lambda module après avoir créé un client dans le code d'initialisation.

# lambda_function.rb
require 'logger'
require 'json'
require 'aws-sdk-lambda'
$client = Aws::Lambda::Client.new()
$client.get_account_settings()

require 'aws-xray-sdk/lambda'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  ...

Dans X-Ray, une trace enregistre des informations relatives à une demande traitée par un ou plusieurs services. Lambda enregistre deux segments par suivi, ce qui a pour effet de créer deux nœuds sur le graphique du service. L’image suivante met en évidence ces deux nœuds :

Le premier nœud sur la gauche représente le service Lambda qui reçoit la demande d’invocation. Le deuxième nœud représente votre fonction Lambda spécifique. L’exemple suivant illustre une trace avec ces deux segments. Les deux sont nommés my-function, mais l’un a pour origine AWS::Lambda et l’autre a pour origine AWS::Lambda::Function. Si le segment AWS::Lambda affiche une erreur, cela signifie que le service Lambda a rencontré un problème. Si le segment AWS::Lambda::Function affiche une erreur, cela signifie que votre fonction a rencontré un problème.

Cet exemple développe le segment AWS::Lambda::Function pour afficher ses trois sous-segments.

Le segment de fonction à l’ancienne contient les sous-segments suivants :

Le segment de fonction de style moderne ne contient pas de sous-segment Invocation. À la place, les sous-segments du client sont directement rattachés au segment de fonction. Pour plus d’informations sur la structure des segments de fonction à l’ancienne et de style moderne, consultez Comprendre les X-Ray traces.

Vous pouvez également utiliser des clients HTTP, enregistrer des requêtes SQL et créer des sous-segments personnalisés avec des annotations et des métadonnées. Pour plus d'informations, consultez le X-Ray SDK pour Ruby dans le Guide du AWS X-Ray développeur.

Activation du suivi actif avec l’API Lambda

Pour gérer la configuration du suivi à l'aide du AWS SDK AWS CLI or, utilisez les opérations d'API suivantes :

L'exemple de AWS CLI commande suivant active le traçage actif sur une fonction nommée my-function.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

Le mode de suivi fait partie de la configuration spécifique de la version lorsque vous publiez une version de votre fonction. Vous ne pouvez pas modifier le mode de suivi sur une version publiée.

Activation du traçage actif avec CloudFormation

Pour activer le traçage sur une AWS::Lambda::Function ressource dans un CloudFormation modèle, utilisez la TracingConfig propriété.

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Pour une AWS::Serverless::Function ressource AWS Serverless Application Model (AWS SAM), utilisez la Tracing propriété.

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Stockage des dépendances d’exécution dans une couche

Si vous utilisez le X-Ray SDK pour instrumenter le code de fonction des clients du AWS SDK, votre package de déploiement peut devenir très volumineux. Pour éviter de télécharger des dépendances d'exécution à chaque fois que vous mettez à jour le code de votre fonction, regroupez le X-Ray SDK dans une couche Lambda.

L'exemple suivant montre une AWS::Serverless::LayerVersion ressource qui stocke le X-Ray SDK pour Ruby.

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-ruby-lib
      Description: Dependencies for the blank-ruby sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - ruby2.5

Avec cette configuration, vous ne mettez à jour les fichiers de couche de bibliothèque que si vous modifiez vos dépendances d’exécution. Étant donné que le package de déploiement de la fonction contient uniquement votre code, cela peut contribuer à réduire les temps de chargement.

La création d'une couche pour les dépendances nécessite des modifications de construction pour générer l'archive des couches avant le déploiement. Pour un exemple fonctionnel, consultez l’exemple d’application blank-ruby.