Node.js Code d'instrumentation dans AWS Lambda

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

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

• AWS Distribution pour OpenTelemetry (ADOT)  : distribution sécurisée, prête pour la production et AWS prise en charge du SDK (OTel). OpenTelemetry

• Kit SDK AWS X-Ray pour Node.js— Un SDK pour générer et envoyer des données de trace à X-Ray.

Chacun des SDK propose des moyens d'envoyer vos données de télémétrie au service. X-Ray Vous pouvez ensuite consulter, filtrer et obtenir des informations sur les indicateurs de performance de votre application afin d'identifier les problèmes et les opportunités d'optimisation. X-Ray

Important

Les outils X-Ray et Powertools pour les AWS Lambda SDK font partie d'une solution d'instrumentation étroitement intégrée proposée par. AWS Les couches ADOT Lambda font partie d’une norme industrielle pour l’instrumentation de traçage qui collecte plus de données en général, mais qui peut ne pas convenir à tous les cas d’utilisation. Vous pouvez implémenter le traçage de bout en bout en X-Ray utilisant l'une ou l'autre des solutions. Pour en savoir plus sur le choix entre les deux, voir Choisir entre la AWS distribution pour Open Telemetry et les SDK. X-Ray

Utiliser ADOT pour instrumenter vos fonctions Node.js

ADOT fournit 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 kit SDK OTel. 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 d’OTel. Pour de plus amples informations, veuillez consulter Configuration personnalisée pour ADOT Collector sur Lambda dans la documentation ADOT.

Pour les Node.js environnements d'exécution, vous pouvez ajouter la couche Lambda AWS gérée pour ADOT 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 Support JavaScript dans la documentation ADOT.

Utiliser le X-Ray SDK pour instrumenter vos fonctions 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 ce kit SDK, ajoutez le package aws-xray-sdk-core aux dépendances de votre application.

Exemple vide- nodejs/package .json

{
  "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 les clients du AWS SDK dans la AWS SDK pour JavaScript v3, encapsulez l'instance du client avec la captureAWSv3Client méthode.

Exemple vide- nodejs/function /index.js — Tracer un AWS Client du SDK

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 est configuré AWS_XRAY_CONTEXT_MISSING pour LOG_ERROR éviter de 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.

Exemple Exemple de code d'initialisation

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

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

Pour de plus amples informations, veuillez consulter Utilisation des variables d’environnement Lambda.

Après avoir ajouté les dépendances appropriées et apporté les modifications de code nécessaires, activez le traçage dans la configuration de votre fonction via la console Lambda ou l'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 :

Pour activer le traçage actif

1. Ouvrez la page Functions (Fonctions) de la console Lambda.

2. Choisissez une fonction.

3. Choisissez Configuration, puis choisissez Outils de surveillance et d’opérations.

4. Dans Outils de surveillance supplémentaires, choisissez Modifier.

5. Sous Signaux CloudWatch d'application et AWS X-Ray choisissez Activer pour les traces de service Lambda.

6. Choisissez Enregistrer.

Activation du suivi avec l’API Lambda

Configurez le suivi sur votre fonction Lambda à l'aide du AWS SDK AWS CLI or, utilisez les opérations d'API suivantes :

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

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.

Activer le traçage avec CloudFormation

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

Exemple fonction-inline.yml — Configuration du traçage

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

Exemple template.yml — Configuration du traçage

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

Interprétation et X-Ray traçabilité

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.

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.

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.

Note

AWS met actuellement en œuvre des modifications au service Lambda. En raison de ces modifications, vous pouvez constater des différences mineures entre la structure et le contenu des messages du journal système et des segments de suivi émis par les différentes fonctions Lambda de votre Compte AWS.

L’exemple de suivi présenté ici illustre le segment de fonction à l’ancienne. Les différences entre les segments à l’ancienne et de style moderne sont décrites dans les paragraphes suivants.

Ces modifications seront mises en œuvre au cours des prochaines semaines, et toutes les fonctions, à l' Régions AWS exception de la Chine et des GovCloud régions, passeront au nouveau format des messages de journal et des segments de suivi.

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

• Initialization (Initialisation) : représente le temps passé à charger votre fonction et à exécuter le code d’initialisation. Ce sous-segment apparaît pour le premier événement traité par chaque instance de votre fonction.

• Invocation – Représente le temps passé à exécuter votre code de gestionnaire.

• Overhead (Travail supplémentaire) – Représente le temps que le fichier d’exécution Lambda passe à se préparer à gérer l’événement suivant.

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 Kit SDK AWS X-Ray pour Node.js dans le AWS X-Ray Guide du développeur.

Tarification

Vous pouvez utiliser le X-Ray traçage gratuitement chaque mois jusqu'à une certaine limite dans le cadre du niveau AWS gratuit. Au-delà de ce seuil, les X-Ray frais de stockage et de récupération des traces sont facturés. Pour en savoir plus, consultez Pricing AWS X-Ray (Tarification).

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

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 ressource AWS::Serverless::LayerVersion qui stocke le Kit SDK AWS X-Ray pour Node.js.

Exemple template.yml — Couche de dépendances

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:
        - nodejs24.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 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-nodejs.