Instrumenter des applications Java sans serveur

L’interface de ligne de commande Datadog permet de modifier les configurations des fonctions Lambda existantes pour instrumenter vos applications sans les redéployer. Il s’agit du moyen le plus rapide de tirer parti de la surveillance sans serveur de Datadog.

1. Installer l’interface de ligne de commande Datadog

   npm install -g @datadog/datadog-ci
   

2. Si vous commencez tout juste à utiliser la surveillance sans serveur Datadog, lancez l’interface de ligne de commande Datadog en mode interactif pour procéder rapidement à la première installation. Vous pouvez ignorer les autres étapes indiquées sur cette page. Pour installer définitivement Datadog pour vos applications de production, ignorez cette étape et suivez les autres étapes pour exécuter la commande de l’interface de ligne de commande Datadog dans vos pipelines de CI/CD après un déploiement normal.

   datadog-ci lambda instrument -i
   

3. Configurer les identifiants AWS

   L’interface de ligne de commande Datadog nécessite un accès au service AWS Lambda et dépend du SDK JavaScript AWS pour résoudre les identifiants. Assurez-vous de configurer vos identifiants AWS à l’aide de la même méthode que celle utilisée lors de l’appel de l’interface de ligne de commande AWS.

4. Configurer le site Datadog

   export DATADOG_SITE="<DATADOG_SITE>"
   

   Remplacez <DATADOG_SITE> par (assurez-vous que le SITE sélectionné à droite est correct).

5. Configurez votre clé d’API Datadog

   Datadog vous recommande d’enregistrer la clé d’API Datadog dans AWS Secrets Manager pour améliorer la sécurité et pour faciliter la rotation. La clé doit être stockée sous forme de chaîne de texte brut (et non en tant que blob JSON). Assurez-vous que vos fonctions Lambda disposent de l’autorisation IAM secretsmanager:GetSecretValue requise.

   export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"
   

   Pour effectuer un test rapide, vous pouvez également définir la clé d’API Datadog sous forme de texte brut :

   export DATADOG_API_KEY="<DATADOG_API_KEY>"
   

6. Instrumenter vos fonctions Lambda

   Remarque : instrumentez d’abord vos fonctions Lambda dans un environnement de type dev ou staging. Si les résultats de votre instrumentation ne vous conviennent pas, exécutez uninstrument avec les mêmes arguments pour annuler les modifications.

   Pour instrumenter vos fonctions Lambda, exécutez la commande suivante.

   datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 11 -e 48
   

   Renseignez les paramètres fictifs comme suit :

   • Remplacez <functionname> et <another_functionname> par les noms de vos fonctions Lambda. Vous pouvez également utiliser --functions-regex pour instrumenter automatiquement plusieurs fonctions dont les noms correspondent à l’expression régulière fournie.
   • Remplacez <aws_region> par le nom de la région AWS.

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

Le plug-in Serverless Datadog configure automatiquement vos fonctions afin qu’elles envoient les métriques, traces et logs à Datadog via l’extension Lambda Datadog.

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

1. Pour installer le plug-in Serverless Datadog :

   serverless plugin install --name serverless-plugin-datadog
   

2. Modifiez votre fichier serverless.yml :

   custom:
     datadog:
       site: <DATADOG_SITE>
       apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
   

   Renseignez les paramètres fictifs comme suit :

   • Remplacez <DATADOG_SITE> par (assurez-vous que le SITE sélectionné à droite est correct).
   • Remplacez <DATADOG_API_KEY_SECRET_ARN> par l’ARN du secret AWS où votre clé d’API Datadog est stockée en toute sécurité. La clé doit être stockée sous forme de chaîne de texte brut (et non en tant que blob JSON). L’autorisation secretsmanager:GetSecretValue est requise. Pour effectuer un test rapide, vous pouvez également utiliser apiKey et définir la clé d’API Datadog sous forme de texte brut.

   Pour obtenir plus de détails ainsi que des paramètres supplémentaires, consultez la documentation relative au plug-in.

La bibliothèque CDK Construct Datadog installe automatiquement Datadog sur vos fonctions à l’aide des couches Lambda. Elle configure vos fonctions afin qu’elles envoient des métriques, traces et logs à Datadog via l’extension Lambda Datadog.

1. Installer la bibliothèque CDK Construct Datadog

   Node.js :

   # For AWS CDK v1
   npm install datadog-cdk-constructs --save-dev
   
   # For AWS CDK v2
   npm install datadog-cdk-constructs-v2 --save-dev
   

   Python :

   # For AWS CDK v1
   pip install datadog-cdk-constructs
   
   # For AWS CDK v2
   pip install datadog-cdk-constructs-v2
   

2. Instrumenter vos fonctions Lambda

   Node.js :

   // For AWS CDK v1
   import { Datadog } from "datadog-cdk-constructs";
   
   // For AWS CDK v2
   import { Datadog } from "datadog-cdk-constructs-v2";
   
   const datadog = new Datadog(this, "Datadog", {
       javaLayerVersion: 11,
       extensionLayerVersion: 48,
       site: "<DATADOG_SITE>",
       apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
   });
   datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
   

   Python :

   # For AWS CDK v1
   from datadog_cdk_constructs import Datadog
   
   # For AWS CDK v2
   from datadog_cdk_constructs_v2 import Datadog
   
   datadog = Datadog(self, "Datadog",
       java_layer_version=11,
       extension_layer_version=48,
       site="<DATADOG_SITE>",
       api_key_secret_arn="<DATADOG_API_KEY_SECRET_ARN>",
     )
   datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
   

   Renseignez les paramètres fictifs comme suit :

   • Remplacez <DATADOG_SITE> par (assurez-vous que le SITE sélectionné à droite est correct).
   • Remplacez <DATADOG_API_KEY_SECRET_ARN> par l’ARN du secret AWS où votre clé d’API Datadog est stockée de façon sécurisée. La clé doit être stockée sous forme de chaîne de texte brut (et non en tant que blob JSON). Assurez-vous que le rôle d’exécution de votre fonction Lambda dispose de l’autorisation IAM secretsmanager:GetSecretValue pour lire la valeur du secret. Pour effectuer un test rapide, vous pouvez utiliser apiKey et définir la clé d’API Datadog sous forme de texte brut.

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

1. Installer l’extension Lambda Datadog

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

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

2. Installer le client APM Java Datadog

   RUN yum -y install tar wget gzip
   RUN wget -O /opt/java/lib/dd-java-agent.jar https://dtdg.co/latest-java-tracer
   

3. Définir les variables d’environnement requises

   • Définissez AWS_LAMBDA_EXEC_WRAPPER sur /opt/datadog_wrapper.
   • Définissez DD_SITE sur (assurez-vous que le SITE sélectionné à droite est correct).
   • Définissez DD_API_KEY_SECRET_ARN sur l’ARN du secret AWS où votre clé d’API Datadog est stockée en toute sécurité. La clé doit être stockée sous forme de chaîne de texte brut (et non en tant que blob JSON). L’autorisation secretsmanager:GetSecretValue est requise. Pour effectuer un test rapide, vous pouvez également utiliser DD_API_KEY et définir la clé d’API Datadog sous forme de texte brut.

Utilisez ce format pour votre ressource Terraform :

resource "aws_lambda_function" "lambda" {
  "function_name" = ...
  ...

  # Assurez-vous de choisir les couches adéquates en fonction de votre architecture Lambda et de vos régions AWS

  layers = [
    <ARN_TRACEUR_DATADOG>,
    <ARN_EXTENSION_DATADOG>
  ]

  environment {
    variables = {
      DD_SITE                     = <SITE_DATADOG>
      DD_API_KEY_SECRET_ARN       = <CLÉ_API>
      AWS_LAMBDA_EXEC_WRAPPER     = "/opt/datadog_wrapper"
    }
  }
}

Renseignez les variables adéquates :

1. Remplacez <ARN_TRACEUR_DATADOG> par l’ARN du traceur Datadog adéquat en fonction de votre type de région :

   AWS REGIONS	LAYERS
   Commercial	arn:aws:lambda:<AWS_REGION>:464622532012:layer:dd-trace-java:11
   GovCloud	arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-java:11

   Dans chaque ARN, remplacez <AWS_REGION> par une région AWS valide, telle que us-east-1.

2. Remplacez <ARN_EXTENSION_DATADOG> par l’ARN de l’extension Lambda Datadog adéquate en fonction de votre région et de votre architecture.

   AWS REGIONS	ARCHITECTURE	LAYERS
   Commercial	x86_64	arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:48
   	arm64	arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:48
   GovCloud	x86_64	arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:48
   	arm64	arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:48

3. Remplacez <SITE_DATADOG> par (assurez-vous que le SITE sélectionné à droite est correct).

4. Remplacez CLÉ_API par l’ARN du secret AWS où votre clé d’API Datadog est stockée de façon sécurisée. La clé doit être stockée sous forme de chaîne de texte brut (et non en tant que blob JSON). L’autorisation secretsmanager:GetSecretValue est requise. Pour effectuer un test rapide, vous pouvez également utiliser DD_API_KEY au lieu de DD_API_KEY_SECRET_ARN et définir la valeur sur votre clé d’API Datadog sous forme de texte brut.

Exemple complet

resource "aws_lambda_function" "lambda" {
  "function_name" = ...
  ...

  # Assurez-vous de choisir les couches adéquates en fonction de votre architecture Lambda et de vos régions AWS

  layers = [
    "arn:aws:lambda:us-east-1:464622532012:layer:dd-trace-java:11",
    "arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Extension:45"
  ]

  environment {
    variables = {
      DD_SITE                     = datadoghq.com
      DD_API_KEY_SECRET_ARN       = "arn:aws..."
      AWS_LAMBDA_EXEC_WRAPPER     = "/opt/datadog_wrapper"
    }
  }
}

1. Installer le traceur Datadog

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

   # Use this format for Lambda deployed in AWS commercial regions
   arn:aws:lambda:<AWS_REGION>:464622532012:layer:dd-trace-java:11
   
   # Use this format for Lambda deployed in AWS GovCloud regions
   arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-java:11
   

   Remplacez <AWS_REGION> par une région AWS valide, telle que us-east-1.

2. Installer l’extension Lambda Datadog

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

   # Use this format for x86-based Lambda deployed in AWS commercial regions
   arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:48
   
   # Use this format for arm64-based Lambda deployed in AWS commercial regions
   arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:48
   
   # Use this format for x86-based Lambda deployed in AWS GovCloud regions
   arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:48
   
   # Use this format for arm64-based Lambda deployed in AWS GovCloud regions
   arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:48
   

   Remplacez <AWS_REGION> par une région AWS valide, telle que us-east-1.

3. Définir les variables d’environnement requises

   • Définissez AWS_LAMBDA_EXEC_WRAPPER sur /opt/datadog_wrapper.
   • Définissez DD_SITE sur (assurez-vous que le SITE sélectionné à droite est correct).
   • Définissez DD_API_KEY_SECRET_ARN sur l’ARN du secret AWS où votre clé d’API Datadog est stockée de façon sécurisée. La clé doit être stockée sous forme de chaîne de texte brut (et non en tant que blob JSON). L’autorisation secretsmanager:GetSecretValue est requise. Pour effectuer un test rapide, vous pouvez également utiliser DD_API_KEY et définir la clé d’API Datadog sous forme de texte brut.