Instrumenter des applications Node.js

Configuration requise

Si vous ne l’avez pas encore fait, installez l’intégration AWS. Datadog pourra ainsi ingérer les métriques Lambda depuis AWS. Après avoir installé l’intégration AWS, suivez ces étapes pour instrumenter votre application afin d’envoyer des métriques, des logs et des traces à Datadog.

Instrumenter des applications sans serveur AWS

Si vous avez déjà configuré le plug-in Serverless Datadog à l’aide du Forwarder Datadog ou si vos fonctions Lambda sont déployées dans la région AWS GovCloud, consultez les instructions d’installation ici.

Configuration

    Le plug-in Serverless Datadog ajoute automatiquement la bibliothèque Lambda Datadog à vos fonctions à l’aide des couches Lambda, et configure vos fonctions de sorte à ce qu’elles envoient les métriques, les traces et les logs à Datadog via l’extension Lambda Datadog.

    Pour installer et configurer le plug-in Serverless Datadog, suivez les étapes suivantes :

    1. Installez le plug-in Serverless Datadog :
      yarn add --dev serverless-plugin-datadog
    2. Ajoutez ce qui suit dans votre fichier serverless.yml :
      plugins:
  - serverless-plugin-datadog
    3. Ajoutez également la section suivante dans votre fichier serverless.yml :
      custom:
  datadog:
    addExtension: true
    apiKey: # Your Datadog API Key goes here.
      Recherchez votre clé d’API Datadog sur la page de gestion des API. Pour prendre connaissance des paramètres supplémentaires, consultez la documentation du plug-in.

    La macro CloudFormation Datadog transforme automatiquement votre modèle d’application SAM dans le but d’ajouter la bibliothèque Lambda Datadog à vos fonctions à l’aide des couches. De plus, elle configure vos fonctions de sorte à ce qu’elles envoient des métriques, des traces et des logs à Datadog via l’extension Lambda Datadog.

    Install

    Exécutez la commande suivante avec vos identifiants AWS pour déployer une pile CloudFormation qui installe la ressource AWS de la macro. Vous ne devez installer la macro qu’une seule fois par région de votre compte. Remplacez create-stack par update-stack pour mettre à jour la macro vers la dernière version.

    aws cloudformation create-stack \
  --stack-name datadog-serverless-macro \
  --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
  --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM

    La macro est désormais déployée et utilisable.

    Instrumenter

    Dans votre fichier template.yml, ajoutez ce qui suit dans la section Transform, après la transformation AWS::Serverless pour SAM.

    Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      nodeLayerVersion: "<VERSION_COUCHE>"
      extensionLayerVersion: "<VERSION_EXTENSION>"
      service: "<SERVICE>" # Facultatif
      env: "<ENV>" # Facultatif

    Remplacez <SERVICE> et <ENV> par les valeurs appropriées, <VERSION_COUCHE> par la version de votre choix de la bibliothèque Lambda Datadog, et <VERSION_EXTENSION> par la version de votre choix de l’extension Lambda Datadog.

    Pour obtenir plus de détails ainsi que des paramètres supplémentaires, consultez la documentation relative à la macro.

    La bibliothèque CDK Constructs Datadog ajoute automatiquement la bibliothèque Lambda Datadog à vos fonctions à l’aide des couches Lambda, et configure vos fonctions de sorte à ce qu’elles envoient les métriques, les traces et les logs à Datadog via l’extension Lambda Datadog.

    Installer la bibliothèque CDK Constructs Datadog

    Exécutez la commande Yarn ou NPM suivante dans votre projet CDK pour installer la bibliothèque CDK Constructs Datadog :

    #Yarn
yarn add --dev datadog-cdk-constructs

#NPM
npm install datadog-cdk-constructs --save-dev

    Instrumenter la fonction

    Importez le module datadog-cdk-construct dans votre application AWS CDK et ajoutez les configurations suivantes :

    import * as cdk from "@aws-cdk/core";
import { Datadog } from "datadog-cdk-constructs";

class CdkStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const datadog = new Datadog(this, "Datadog", { 
        nodeLayerVersion: <VERSION_COUCHE>, 
        extensionLayerVersion: <VERSION_EXTENSION>, 
        apiKey: <CLÉ_API_DATADOG>,
    });
    datadog.addLambdaFunctions([<FONCTIONS_LAMBDA>]);    
  }
}

    Pour remplir les paramètres fictifs, procédez comme suit :

    • Remplacez <DATADOG_API_KEY> par votre clé d’API Datadog sur la page de gestion des API.
    • Remplacez <VERSION_COUCHE> par la version de votre choix de la couche Lambda Datadog (consultez les dernières versions).
    • Remplacez <VERSION_EXTENSION> par la version de votre choix de l’extension Lambda Datadog (consultez les dernières versions).

    Pour obtenir plus de détails ainsi que des paramètres supplémentaires, consultez la page NPM relative au CDK Datadog (en anglais).

    Ce service est en bêta publique. Si vous souhaitez nous faire part de vos remarques, contactez l'assistance Datadog.

    Utilisez l’interface de ligne de commande Datadog pour configurer l’instrumentation sur vos fonctions Lambda dans vos pipelines CI/CD. La commande de l’interface de ligne de commande ajoute automatiquement la bibliothèque Lambda Datadog à vos fonctions à l’aide des couches Lambda. Elle configure vos fonctions de façon à envoyer des métriques, traces et logs à Datadog.

    Install

    Installez l’interface de ligne de commande Datadog avec NPM ou Yarn :

    # NPM
npm install -g @datadog/datadog-ci

# Yarn
yarn global add @datadog/datadog-ci

    Instrumenter

    Pour instrumenter la fonction, exécutez la commande suivante avec vos identifiants AWS. Remplacez <nomfonction> et <autre_nomfonction> par les noms de vos fonctions Lambda, <région_aws> par le nom de la région AWS, <version_couche> par la version de votre choix de la bibliothèque Lambda Datadog et <version_extension> par la version de votre choix de l’extension Lambda Datadog.

    datadog-ci lambda instrument -f <nomfonction> -f <autre_nomfonction> -r <région_aws> -v <version_couche> -e <version_extension>

    Par exemple :

    datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v 26 -e 8


    datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v 26 -e 8

    Pour obtenir plus de détails ainsi que des paramètres supplémentaires, consultez la documentation relative à l’interface de ligne de commande.

    Install

    Si vous déployez votre fonction Lambda en tant qu’image de conteneur, vous ne pouvez pas utiliser la bibliothèque Lambda Datadog en tant que couche Lambda. À la place, vous devez installer la bibliothèque Lambda Datadog en tant que dépendance de votre fonction directement dans l’image. Si vous utilisez le tracing Datadog, vous devez également installer dd-trace.

    NPM :

    npm install --save datadog-lambda-js dd-trace

    Yarn :

    yarn add datadog-lambda-js dd-trace

    Remarque : la version mineure du package datadog-lambda-js correspond toujours à la version de la couche. Par exemple, datadog-lambda-js v0.5.0 correspond au contenu de la version 5 de la couche.

    Configurer

    Installer l’extension Lambda Datadog

    Ajoutez l’extension Lambda Datadog à votre image de conteneur en ajoutant ce qui suit à votre Dockerfile :

    COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/extensions/ /opt/extensions

    Remplacez <TAG> par un numéro de version spécifique (par exemple, 7) ou par latest. Accédez au référentiel Amazon ECR pour consulter la liste complète des tags disponibles.

    Configurer la fonction

    1. Définissez la valeur CMD de votre image sur node_modules/datadog-lambda-js/dist/handler.handler. Vous pouvez effectuer cette opération dans AWS ou directement dans votre Dockerfile. Remarque : la valeur définie dans AWS remplace la valeur définie dans le Dockerfile, si vous avez défini les deux.
    2. Définissez les variables d’environnement suivantes dans AWS :
    • Définissez DD_LAMBDA_HANDLER sur votre gestionnaire d’origine, par exemple myfunc.handler.
    • Définissez DD_TRACE_ENABLED sur true.
    • Définissez DD_FLUSH_TO_LOG sur true.
    • Définissez DD_API_KEY sur votre clé d’API Datadog sur la page de gestion des API.
    1. Si vous le souhaitez, ajoutez des tags service et env avec les valeurs appropriées dans votre fonction.

    Install

    La bibliothèque Lambda Datadog peut être importée en tant que couche ou en tant que package JavaScript.

    La version mineure du package datadog-lambda-js correspond toujours à la version de la couche. Par exemple, datadog-lambda-js v0.5.0 correspond au contenu de la version 5 de la couche.

    Utiliser la couche

    Configurez les couches pour votre fonction Lambda à l’aide de l’ARN, en respectant le format suivant :

    arn:aws:lambda:<RÉGION_AWS>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>


    arn:aws-us-gov:lambda:<RÉGION_AWS>:002406178527:layer:Datadog-<RUNTIME>:<VERSION>

    Les options RUNTIME disponibles sont Node10-x et Node12-x. Pour VERSION, consultez la dernière version. Exemple :

    arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Node12-x:25


    arn:aws-us-gov:lambda:us-gov-east-1:002406178527::layer:Datadog-Node12-x:25

    Utiliser le package

    NPM :

    npm install --save datadog-lambda-js

    Yarn :

    yarn add datadog-lambda-js

    Consultez la dernière version.

    Installer l’extension Lambda Datadog

    Configurez les couches pour votre fonction Lambda à l’aide de l’ARN, en respectant le format suivant :

    arn:aws:lambda:<RÉGION_AWS>:464622532012:layer:Datadog-Extension:<VERSION_EXTENSION>


    arn:aws-us-gov:lambda:<RÉGION_AWS>:002406178527:layer:Datadog-Extension:<VERSION_EXTENSION>

    Pour VERSION_EXTENSION, consultez la dernière version.

    Configurer

    Pour configurer la fonction, suivez les étapes ci-dessous :

    1. Définissez le gestionnaire de votre fonction sur /opt/nodejs/node_modules/datadog-lambda-js/handler.handler si vous utilisez la couche, ou sur node_modules/datadog-lambda-js/dist/handler.handler si vous utilisez le package.
    2. Définissez la variable d’environnement DD_LAMBDA_HANDLER sur votre gestionnaire d’origine, comme myfunc.handler.
    3. Définissez la variable d’environnement DD_TRACE_ENABLED sur true.
    4. Définissez la variable d’environnement DD_API_KEY sur votre clé d’API Datadog, disponible sur la page de gestion des API.
    5. Vous pouvez également définir des tags service et env pour votre fonction avec des valeurs correspondantes.

    Explorer la surveillance sans serveur de Datadog

    Après avoir configuré votre fonction en suivant la procédure ci-dessus, vous pouvez visualiser vos métriques, logs et traces sur la page Serverless principale.

    Tagging de service unifié

    Bien que cette opération soit facultative, Datadog vous recommande fortement d’ajouter les tags env, service et version à vos applications sans serveur. Pour ce faire, suivez la documentation relative au tagging de service unifié.

    Collecter les logs à partir des ressources sans serveur AWS

    Les logs d’un environnement sans serveur générés par des ressources gérées, outre les fonctions Lambda AWS, peuvent être très utiles pour identifier la cause d’origine des problèmes liés à vos applications sans serveur. Nous vous recommandons de transmettre les logs provenant des ressources gérées suivantes à votre environnement :

    • API : API Gateway, AppSync, ALB
    • Files d’attente et flux : SQS, SNS, Kinesis
    • Datastores : DynamoDB, S3, RDS, etc.

    Pour collecter des logs depuis des ressources AWS autres que des fonctions Lambda, installez le Forwarder Datadog et configurez-le de façon à l’abonner à tous les groupes de logs CloudWatch des ressources gérées.

    Surveiller une logique opérationnelle personnalisée

    Si vous souhaitez envoyer une métrique custom ou une span personnalisée, consultez l’exemple de code ci-dessous :

    const { sendDistributionMetric, sendDistributionMetricWithDate } = require("datadog-lambda-js");
const tracer = require("dd-trace");

// Envoyer une span personnalisée appelée "sleep"
const sleep = tracer.wrap("sleep", (ms) => {
  return new Promise((resolve) => setTimeout(resolve, ms));
});

exports.handler = async (event) => {
  // Ajouter des tags personnalisés à la span de la fonction Lambda,
  // ne fonctionne PAS si le tracing X-Ray est activé
  const span = tracer.scope().active();
  span.setTag('customer_id', '123456');

  await sleep(100);

  // Envoyer une span personnalisée
  const sandwich = tracer.trace('hello.world', () => {
    console.log('Hello, World!');
  });

  // Envoyer une métrique custom
  sendDistributionMetric(
    "coffee_house.order_value", // nom de la métrique
    12.45, // valeur de la métrique
    "product:latte", // tag
    "order:online", // autre tag
  );

  // Envoyer une métrique custom avec un timestamp
  sendDistributionMetricWithDate(
    "coffee_house.order_value", // nom de la métrique
    12.45, // valeur de la métrique
    new Date(Date.now()), // date, doit être dans les 20 dernières minutes
    "product:latte", // tag
    "order:online", // autre tag
  );

  const response = {
    statusCode: 200,
    body: JSON.stringify("Hello from serverless!"),
  };
  return response;
};

    Pour en savoir plus sur l’envoi de métriques custom, consultez cette page. Pour obtenir plus d’informations sur l’instrumentation personnalisée, consultez la documentation dédiée.

    Pour aller plus loin

    Documentation, liens et articles supplémentaires utiles:

    Plug-in Serverless DatadogDOCUMENTATION more more Macro Serverless DatadogDOCUMENTATION more more CLI Serverless DatadogDOCUMENTATION more more Tagging d'applications sans serveurDOCUMENTATION more more Tracing d'applications sans serveurDOCUMENTATION more more Envoyer des métriques custom depuis des applications sans serveurDOCUMENTATION more more