Instrumentation du code Node.js dans AWS Lambda

Lambda s'intègre pour vous aider AWS X-Ray à suivre, à déboguer et à optimiser les applications Lambda. Vous pouvez utiliser X-Ray pour suivre une demande lorsque celle-ci parcourt les ressources de votre application, qui peuvent inclure des fonctions Lambda et d'autres services AWS .

Pour envoyer des données de suivi à X-Ray, vous pouvez utiliser l'une des deux SDK bibliothèques suivantes :

Chacune d'entre elles SDKs propose des moyens d'envoyer vos données de télémétrie au service X-Ray. Vous pouvez ensuite utiliser X-Ray pour afficher, filtrer et avoir un aperçu des métriques de performance de votre application, afin d'identifier les problèmes et les occasions d'optimiser votre application.

Utilisation ADOT pour instrumenter vos fonctions Node.js

ADOTfournit des couches Lambda entièrement gérées qui regroupent tout ce dont vous avez besoin pour collecter des données de télémétrie à l'aide du. OTel SDK En consommant cette couche, vous pouvez instrumenter vos fonctions Lambda sans avoir à modifier le code de fonction. Vous pouvez également configurer votre couche pour effectuer une initialisation personnalisée deOTel. Pour plus d'informations, consultez la section Configuration personnalisée du ADOT collecteur sur Lambda dans la ADOT documentation.

Pour les environnements d'exécution de Node.js, vous pouvez ajouter la couche Lambda AWS gérée ADOT pour Javascript afin d'instrumenter automatiquement vos fonctions. Pour obtenir des instructions détaillées sur la façon d'ajouter cette couche, consultez AWS Distro for OpenTelemetry Lambda JavaScript Support ADOT dans la documentation.

Utiliser le X-Ray SDK pour instrumenter les fonctions de votre Node.js

Pour enregistrer des détails sur les appels effectués par votre fonction Lambda à d'autres ressources de votre application, vous pouvez également utiliser le Kit SDK AWS X-Ray pour Node.js. Pour obtenir leSDK, ajoutez le aws-xray-sdk-core package aux dépendances de votre application.

{
  "name": "blank-nodejs",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "jest": "29.7.0"
  },
  "dependencies": {
    "@aws-sdk/client-lambda": "3.345.0",
    "aws-xray-sdk-core": "3.5.3"
  },
  "scripts": {
    "test": "jest"
  }
}

Pour instrumenter AWS SDK les clients dans la AWS SDK for JavaScript v3, encapsulez l'instance du client avec la captureAWSv3Client méthode.

const AWSXRay = require('aws-xray-sdk-core');
const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda');

// Create client outside of handler to reuse
const lambda = AWSXRay.captureAWSv3Client(new LambdaClient());

// Handler
exports.handler = async function(event, context) {
    event.Records.forEach(record => {
  ...

Le moteur d'exécution Lambda définit certaines variables d'environnement pour configurer le X-Ray. SDK Par exemple, Lambda définit sur pour éviter AWS_XRAY_CONTEXT_MISSING de LOG_ERROR générer des erreurs d'exécution depuis le X-Ray. SDK Pour définir une stratégie manquante de contexte personnalisée, remplacez la variable d'environnement dans votre configuration de fonction pour n'avoir aucune valeur, puis vous pouvez définir la stratégie manquante de contexte par programme.

const AWSXRay = require('aws-xray-sdk-core');

// Configure the context missing strategy to do nothing
AWSXRay.setContextMissingStrategy(() => {});

Pour de plus amples informations, veuillez consulter Utiliser les variables d'environnement Lambda pour configurer les valeurs dans le code.

Après avoir ajouté les dépendances correctes et apporté les modifications de code nécessaires, activez le suivi dans la configuration de votre fonction via la console Lambda ou le. API

Activation du suivi avec la console Lambda

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

Activation du traçage avec le Lambda API

Configurez le suivi sur votre fonction Lambda avec AWS CLI ou utilisez AWS SDK les opérations suivantes : API

L'exemple de AWS CLI commande suivant active le suivi 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 avec AWS CloudFormation

Pour activer le suivi d'une AWS::Lambda::Function ressource dans un AWS 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
      ...

Interprétation d'un suivi X-Ray

Votre fonction a besoin d'une autorisation pour 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. Dans le cas contraire, ajoutez la AWSXRayDaemonWriteAccesspolitique au rôle d'exécution.

Une fois que vous avez configuré le suivi actif, vous pouvez observer des demandes spécifiques via votre application. Le graphique de services X-Ray affiche 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 située en haut traite les erreurs qui apparaissent dans le groupe de journaux du premier et utilise le AWS SDK pour appeler X-Ray, Amazon Simple Storage Service (Amazon S3) et Amazon CloudWatch Logs.

X-Ray ne trace pas toutes les requêtes vers votre application. X-Ray applique un algorithme d'échantillonnage pour s'assurer que le suivi est efficace, 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 d'échantillonnage des rayons X pour vos fonctions.

Dans X-Ray, un suivi enregistre des informations sur une demande traitée par un ou plusieurs services. Lambda enregistre 2 segments par trace, ce qui crée deux nœuds sur le graphe de 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 une origine de AWS::Lambda et l'autre a une origine deAWS::Lambda::Function. Si le AWS::Lambda segment affiche une erreur, cela signifie que le service Lambda a rencontré un problème. Si le AWS::Lambda::Function segment affiche une erreur, cela signifie que votre fonction a rencontré un problème.

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

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

Le segment de fonction du nouveau style ne contient pas de Invocation sous-segment. Au lieu de cela, les sous-segments clients sont rattachés directement au segment fonctionnel. Pour plus d'informations sur la structure des segments de fonction de l'ancien et du nouveau style, consultezComprendre les suivis X-Ray.

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

Stockage des dépendances d'exécution dans une couche (X-RaySDK)

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

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

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

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 de dépendances nécessite des modifications de génération pour créer l'archive des couches avant le déploiement. Pour un exemple fonctionnel, consultez l'exemple d'application blank-nodejs.