Fonction de trace AWS Lambda native pour Node.js

La configuration d'Instana AutoTrace pour Node.js vous permet de suivre les fonctions AWS Lambda en utilisant la couche Instana Lambda et un gestionnaire de fonctions personnalisé. Cette approche ne nécessite aucune modification de code de la fonction Lambda et s'effectue par le biais d'une simple configuration. Cette configuration peut parfaitement être automatisée ou incluse dans un pipeline de déploiement Lambda.

Pour activer le suivi des fonctions Lambda Node.js, procédez comme suit :

1. Ajoutez la couche Instana Lambda à votre fonction.

   1. Dans la page de configuration de votre fonction Lambda, cliquez sur la Layers case, puis sur Add a layer.
   2. Dans la fenêtre contextuelle qui s'ouvre, sélectionnez Fournir un ARN de version de couche, puis copiez et collez l'ARN correspondant à votre région pour la couche Instana Lambda. Vous trouverez l'ARN approprié pour la couche Instana Lambda dans la section Couches Instana Lambda.

2. Configurez le gestionnaire Lambda. Définissez le gestionnaire à instana-aws-lambda-auto-wrap.handler si vous utilisez CommonJS. Définir le gestionnaire sur instana-aws-lambda-auto-wrap-esm.handler si vous utilisez les modules ES ( ES6 ) (disponibles à partir de la version de couche 223).

   Pour modifier les paramètres du gestionnaire Lambda, consultez la section "Paramètres de base" sur la page de configuration.

   

   Cliquez sur Editer et insérez instana-aws-lambda-auto-wrap.handler dans la zone "Gestionnaire".

   

   La couche Instana Lambda déclenche automatiquement le gestionnaire d'exécution par défaut Node.js index.handler. Si vous utilisez un gestionnaire personnalisé, spécifiez votre gestionnaire dans la variable d'environnement LAMBDA_HANDLER pour notifier la couche Lambda d'Instana. Voir la section suivante pour toutes les variables d'environnement qui doivent être définies.

   La page de configuration Lambda peut afficher un avertissement tel que Lambda ne peut pas trouver le fichier instana-aws-lambda-auto-wrap.js. Cet avertissement peut également s'afficher ultérieurement lors du retour à la page de configuration. Ne vous laissez pas distraire par cet avertissement. Le gestionnaire réside dans la couche Instana Lambda, mais la page de configuration d'AWS Lambda n'en tient pas compte.

3. Configurez les variables d'environnement. Ajoutez les variables d'environnement suivantes :

   • INSTANA_ENDPOINT_URL: Il s'agit de votre point final de surveillance sans serveur. Veillez à utiliser la valeur correcte pour votre région qui commence par https://serverless-.
   • INSTANA_AGENT_KEY: Votre clé d'agent.
   • LAMBDA_HANDLER: Définissez votre gestionnaire personnalisé. Si votre fichier principal est myModule.js, qui exporte la fonction myHandler, définissez la variable d'environnement myModule.myHandler. La valeur par défaut est index.handler.

   Dans l'exemple suivant, le gestionnaire Lambda principal d'origine est index.js, et vous n'avez donc pas besoin de définir la variable d'environnement LAMBDA_HANDLER.

   Dans l'exemple suivant, le gestionnaire Lambda principal d'origine est server.js, et vous devez donc définir la variable d'environnement LAMBDA_HANDLER sur server.handler.

   Vous pouvez également obtenir les valeurs correctes pour ces variables d'environnement en allant dans votre installation Instana, cliquez sur... More -> Agents -> Installation des agents Instana -> Plate-forme : AWS -> Technologie : AWS Lambda.

4. Enregistrez la définition de la fonction Lambda.

Toutes les étapes décrites précédemment peuvent être effectuées soit via la console web AWS, soit via l'un des outils de gestion habituels de AWS, comme par exemple :

• l' interface de ligne de commande aws
• le framework sans serveur cli
• le kit de développement AWS Cloud

Voici un exemple de commande CLI aws qui pourrait servir de point de départ si vous souhaitez automatiser l'intégration d'Instana de vos instances AWS Lambda :

# Do not copy and paste this verbatim!
# It will overwrite any previously defined collection of layers and
# environment variables.
aws --region $YOUR_REGION lambda update-function-configuration \
  --function-name $YOUR_LAMBDA_FUNCTION_NAME \
  --layers $INSTANA_LAYER_ARN \
  --handler instana-aws-lambda-auto-wrap.handler \
  --environment ""Variables={INSTANA_ENDPOINT_URL=... , INSTANA_AGENT_KEY=... , ...}""
 

Au lieu d'utiliser la couche Instana Lambda, vous pouvez également envisager d'installer manuellement le package npm @instana/aws-lambda :

1. Ajoutez la dépendance @instana/aws-lambda à votre projet en exécutant npm install -S @instana/aws-lambda (ou yarn add @instana/aws-lambda) dans le répertoire de votre projet. Cette commande ajouter le package à votre dossier node_modules et enregistre la dépendance dans votre fichier package.json.
2. Ajouter les variables d'environnement INSTANA_ENDPOINT_URL et INSTANA_AGENT_KEY avec les valeurs requises.
3. Modifiez le code de la fonction conformément à la section Enveloppe manuelle du gestionnaire.

Si votre équipe utilise des déploiements Lambda basés sur des conteneurs, vous pouvez utiliser nos conteneurs de base sur icr.io/instana/aws-lambda-nodejs ou inclure l'extrait suivant dans votre fichier Docker et définir les arguments de temps de construction aux versions appropriées.

Instana ne prend actuellement en charge que l'architecture x86_64 .

Cette image n'est pas destinée à être utilisée dans les environnements FedRAMP-compliant.

# This is the container image that delivers Instana's monitoring capabilities.
# It will not become the base image for your Lambda container image, it just provides a few files.
FROM icr.io/instana/aws-lambda-nodejs:latest as instana-layer

# This is the actual base image for your Lambda container image. You can also use any other base image that is suitable
# for container image based Lambda functions.
FROM public.ecr.aws/lambda/nodejs:14

# Copy Instana's Node.js monitoring components into your Lambda container image.
COPY --from=instana-layer /opt/extensions/ /opt/extensions/
COPY --from=instana-layer /opt/nodejs/ /opt/nodejs/

# The remainder of your Dockerfile, as it was without adding the Instana layer. The following is just an example:
COPY index.js package.json package-lock.json /var/task/
WORKDIR /var/task
RUN npm install

# Override the CMD. This can also be done as a parameter override outside of the Dockerfile, for example in the AWS console.
# If you use ES modules, use CMD [ "instana-aws-lambda-auto-wrap-esm.handler" ] instead.
CMD [ "instana-aws-lambda-auto-wrap.handler" ]
 

Au lieu de icr.io/instana/aws-lambda-nodejs:latest, vous pouvez également utiliser une version spécifique du module Instana npm @instana/aws-lambda supérieure ou égale à 1.137.2 (voir CHANGELOG ), comme par exemple :

FROM icr.io/instana/aws-lambda-nodejs:1.140.1 as instana-layer
 

Ou bien vous ne pouvez épingler que la version majeure, tout en autorisant les versions mineures ou correctives plus récentes :

FROM icr.io/instana/aws-lambda-nodejs:1 as instana-layer
 

Modifiez le site serverless.yml pour intégrer le traçage Instana avec le Serverless Framework. Suivez ces étapes :

1. Copiez l' ARN du calque dans la liste et ajoutez l'ARN à la section des calques de la définition de la fonction cible.

2. Ajoutez les variables d'environnement INSTANA_AGENT_KEY, INSTANA_ENDPOINT_URL et LAMBDA_HANDLER. Pour plus d'informations, voir Instana AutoTrace setup.

Voir l'exemple suivant serverless.yml:

service: service-a

provider:
  name: aws
  runtime: nodejs16.x
  stage: dev
  region: us-east-2

functions:
  with-layer:
    environment:
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:111
    handler: instana-aws-lambda-auto-wrap.handler
 

Les ARNs de la dernière version des couches Lambda de AWS pour les runtimes Lambda listés dans Supported Runtimes sont les suivants, par région :

En d'autres termes, le modèle est arn:aws:lambda:${region}:410797082306:layer:instana-nodejs:${layer-version} (ou arn:aws-cn:lambda:${region}:107998019096:layer:instana-nodejs:${layer-version} pour les régions AWS en Chine).

Veillez à toujours utiliser les versions les plus récentes et à mettre à jour la version de la couche que vous utilisez à intervalles réguliers afin de bénéficier des nouvelles fonctionnalités et des corrections que nous apportons lors de la publication d'une nouvelle version de la couche.