Instrumenter des applications Python sans serveur

Si vos fonctions Lambda reposent sur la version 3.6 ou une version antérieure de Python, ou si vous avez déjà configuré vos fonctions Lambda à l'aide du Forwarder Datadog, consultez la documentation relative à l'instrumentation à l'aide du Forwarder Datadog.
Si vos fonctions Lambda sont déployées dans un VPC sans accès à Internet, vous pouvez transmettre des données avec AWS PrivateLink pour le site datadoghq.com Datadog ou avec un proxy pour tous les autres sites.

Installation

Datadog propose de nombreuses méthodes différentes pour instrumenter vos applications sans serveur. Choisissez celle qui répond le mieux à vos besoins ci-dessous. Nous vous conseillons d’utiliser l’interface de ligne de commande Datadog.

    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. Pour installer définitivement Datadog pour vos applications de production, ignorez cette étape et suivez les autres étapes afin d’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. Configurer la clé d’API Datadog

      Datadog vous recommande d’enregistrer la clé d’API Datadog dans AWS Secrets Manager pour plus de sécurité et pour faciliter la rotation. La clé doit être stockée sous forme de chaîne de texte brut (et non un 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>"

      À des fins de test rapide, vous pouvez également définir la clé d’API Datadog en 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 l’instrumentation ne vous conviennent pas, exécutez uninstrument avec les mêmes arguments pour annuler les modifications.

      Pour instrumenter vos fonctions Lambda, lancez la commande suivante.

      datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 73 -e 43

      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 <région_aws> 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 vos fonctions afin qu’elles envoient des 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. Mettez à jour votre fichierserverless.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 un blob JSON). L’autorisation secretsmanager:GetSecretValue est requise. Pour 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 du plug-in][4].

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

    1. Installer la macro CloudFormation Datadog

      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 installer la dernière version de la macro.

      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.

    2. Instrumenter vos fonctions Lambda

      Ajoutez la transformation DatadogServerless après la transformation AWS::Serverless sous la section Transform de votre fichier template.yml pour SAM.

      Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      pythonLayerVersion: 73
      extensionLayerVersion: 43
      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 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 macro.

    La bibliothèque CDK Construct Datadog installe automatiquement Datadog sur vos fonctions à l’aide des couches Lambda. De plus, 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

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

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

    2. Instrumenter vos fonctions Lambda

      # 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",
    python_layer_version=73,
    extension_layer_version=43,
    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 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 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 la bibliothèque Lambda Datadog

      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 dans l’image.

      pip install datadog-lambda

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

    2. 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, 43) ou par latest. Accédez au référentiel Amazon ECR pour consulter la liste complète des tags disponibles.

    3. Rediriger la fonction du gestionnaire

      • Définissez la valeur CMD de votre image sur datadog_lambda.handler.handler. Vous pouvez effectuer cette opération dans AWS ou directement dans votre Dockerfile. Notez que la valeur définie dans AWS est prioritaire sur la valeur définie dans le Dockerfile, si vous avez défini les deux.
      • Définissez la variable d’environnement DD_LAMBDA_HANDLER sur votre gestionnaire d’origine, comme myfunc.handler.

      Remarque : si vous utilisez un outil de sécurité ou de surveillance tiers qui est incompatible avec la redirection du gestionnaire Datadog, vous pouvez appliquer le wrapper Datadog dans le code de votre fonction.

    4. Configurer le site Datadog, la clé d’API et le tracing

      • Définissez la variable d’environnement DD_SITE sur (assurez-vous que le SITE sélectionné à droite est correct).
      • Définissez la variable d’environnement 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.
      • Définissez la variable d’environnement DD_TRACE_ENABLED sur true.
    Si vous n'utilisez pas l'un des outils de développement sans serveur pris en charge par Datadog, tels que Serverless Framework ou AWS CDK, Datadog vous recommande vivement d'instrumenter vos applications sans serveur avec l'interface de ligne de commande Datadog.

    1. Installer la bibliothèque Lambda Datadog

      La bibliothèque Lambda Datadog peut être importée en tant que couche (conseillé) OU en tant que package Python.

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

      • Option A : configurez les couches pour votre fonction Lambda à l’aide de l’ARN, en respectant le format ci-dessous :

        # Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:73

# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>-ARM:73

# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:73

# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>-ARM:73

        Remplacez <AWS_REGION> par une région AWS valide, comme us-east-1. Les options RUNTIME disponibles sont Python37, Python38 et Python39.

      • Option B : si vous ne pouvez pas utiliser la couche Lambda Datadog prédéfinie, vous avez la possibilité d’installer localement le package datadog-lambda et ses dépendances dans le dossier du projet de votre fonction via votre gestionnaire de package Python préféré, par exemple pip.

        pip install datadog-lambda -t ./

        Remarque : datadog-lambda dépend de ddtrace, qui a recours à des extensions natives ; il doit donc être installé et compilé dans un environnement Linux avec la bonne architecture (x86_64 ou arm64). Par exemple, vous pouvez utiliser dockerizePip pour le plug-in Serverless Framework et –use-container pour AWS SAM. Pour en savoir plus, consultez la documentation relative à l’ajout de dépendances à votre package de déploiement de fonction.

        Consultez la dernière version.

    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:43

# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:43

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

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

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

    3. Rediriger la fonction du gestionnaire

      • Définissez le gestionnaire de votre fonction sur datadog_lambda.handler.handler.
      • Définissez la variable d’environnement DD_LAMBDA_HANDLER sur votre gestionnaire d’origine, comme myfunc.handler.

      Remarque : si vous utilisez un outil de sécurité ou de surveillance tiers qui est incompatible avec la redirection du gestionnaire Datadog, vous pouvez appliquer le wrapper Datadog dans le code de votre fonction.

    4. Configurer le site Datadog, la clé d’API et le tracing

      • Définissez la variable d’environnement DD_SITE sur (assurez-vous que le SITE sélectionné à droite est correct).
      • Définissez la variable d’environnement 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, plutôt que dans un 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.
      • Définissez la variable d’environnement DD_TRACE_ENABLED sur true.

    5. Enregistrer le middleware (AWS Chalice uniquement)

      Si vous utilisez AWS Chalice, vous devez installer datadog-lambda avec pip et enregistrer datadog_lambda_wrapper en tant que middleware dans votre app.py :

      from chalice import Chalice, ConvertToMiddleware
from datadog_lambda.wrapper import datadog_lambda_wrapper

app = Chalice(app_name='hello-chalice')

app.register_middleware(ConvertToMiddleware(datadog_lambda_wrapper))

@app.route('/')
def index():
    return {'hello': 'world'}

    Et ensuite ?

    • Vous pouvez désormais afficher les métriques, les logs et les traces sur la Page d’accueil sans serveur.
    • Consultez l’exemple de code pour [surveiller une logique opérationnelle personnalisée](#surveiller-une-logique operationnelle-personnalisee).
    • Consultez le guide de dépannage si vous ne parvenez pas à recueillir les données de télémétrie.
    • Examinez les configurations avancées pour :
      • Associer des données de télémétrie à l’aide de tags
      • Recueillir des données de télémétrie pour AWS API Gateway, SQS, etc.
      • Capturer les charges utiles des requêtes et des réponses Lambda
      • Associer les erreurs de vos fonctions Lambda à votre code source
      • Filtrer ou nettoyer des informations sensibles des logs ou des traces

    Surveiller une logique opérationnelle personnalisée

    Pour surveiller votre logique opérationnelle personnalisée, envoyez une métrique custom ou une span via l’exemple de code ci-dessous. Pour découvrir plus d’options, consultez la documentation relative à l’envoi de métriques custom pour des applications sans serveur ainsi que le guide APM pour l’instrumentation personnalisée.

    import time
from ddtrace import tracer
from datadog_lambda.metric import lambda_metric

def lambda_handler(event, context):
    # ajouter des tags personnalisés à la span de la fonction Lambda,
    # ne fonctionne PAS lorsque le tracing X-Ray est activé
    current_span = tracer.current_span()
    if current_span:
        current_span.set_tag('customer.id', '123456')

    # envoyer une span personnalisée
    with tracer.trace("hello.world"):
        print('Hello, World!')

    # envoyer une métrique custom
    lambda_metric(
        metric_name='coffee_house.order_value',
        value=12.45,
        tags=['product:latte', 'order:online']
    )

    return {
        'statusCode': 200,
        'body': get_message()
    }

# tracer une fonction
@tracer.wrap()
def get_message():
    return 'Hello from serverless!'

    Pour aller plus loin

    Documentation, liens et articles supplémentaires utiles:

    Configurer la surveillance sans serveurDOCUMENTATION more more Dépannage de la surveillance sans serveurDOCUMENTATION more more Envoyer des métriques custom depuis des applications sans serveurDOCUMENTATION more more