Instrumenter des applications Python sans serveur avec le Forwarder Datadog

Docs > Informatique sans serveur > Guides d'utilisation de la surveillance sans serveur > Instrumenter des applications Python sans serveur avec le Forwarder Datadog

Présentation

Si vous commencez tout juste à utiliser la surveillance sans serveur Datadog, suivez plutôt les instructions d'instrumentation des fonctions Lambda avec l'extension Lambda Datadog. Si vous avez configuré la surveillance sans serveur Datadog avec le Forwarder Datadog avant que les fonctionnalités Lambda clés en main ne soient proposées, consultez ce guide pour gérer votre instance.

Prérequis

Pour ingérer des traces AWS Lambda, des métriques optimisées, des métriques custom et des logs, vous devez utiliser la fonction Lambda du Forwarder Datadog.

Procédure à suivre

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.

Vous pouvez également ajouter la commande à vos pipelines de CI/CD pour instrumenter toutes vos applications sans serveur. Lancez la commande après le déploiement normal de votre application sans serveur, de sorte que les modifications apportées par l’interface de ligne de commande Datadog ne soient pas écrasées.

Installation

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

Instrumentation

Pour instrumenter la fonction, exécutez la commande suivante avec vos identifiants AWS :

datadog-ci lambda instrument -f <nomfonction> -f <autre_nomfonction> -r <région_aws> -v <version_couche> --forwarder <arn_forwarder>

Renseignez les paramètres fictifs comme suit :

Remplacez <nomfonction> et <autre_nomfonction> par les noms de vos fonctions Lambda.
Remplacez <région_aws> par le nom de la région AWS.
Remplacez <version_couche> par la version souhaitée de la bibliothèque Lambda Datadog. La dernière version est 101.
Remplacez <arn_forwarder> par l’ARN du Forwarder (voir la documentation sur le Forwarder).

Par exemple :

datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v 101 --forwarder "arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder"

Si votre fonction Lambda est configurée de façon à utiliser la signature de code, vous devez ajouter l’ARN du profil de signature de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) à la configuration de la signature de code de votre fonction avant de pouvoir l’instrumenter avec l’interface de ligne de commande Datadog.

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

Le plug-in Serverless Datadog ajoute automatiquement la bibliothèque Lambda Datadog à vos fonctions à l’aide d’une couche. Il configure également vos fonctions de façon à envoyer des métriques, traces et logs à Datadog par l’intermédiaire du Forwarder Datadog.

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

Installez le plug-in Serverless Datadog :

yarn add --dev serverless-plugin-datadog

Ajoutez ce qui suit dans votre fichier serverless.yml :
```
plugins:
  - serverless-plugin-datadog
```
Ajoutez également la section suivante dans votre fichier serverless.yml :
```
custom:
  datadog:
    forwarderArn: # The Datadog Forwarder ARN goes here.
```
Pour en savoir plus sur l’ARN du Forwarder Datadog ou sur l’installation, cliquez ici. Pour obtenir 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 de couches. Elle configure également vos fonctions de façon à envoyer des métriques, traces et logs à Datadog par l’intermédiaire du Forwarder Datadog.

Installation

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.

Instrumentation

Pour instrumenter une fonction, ajoutez ce qui suit dans la section Transform de votre fichier template.yml, après la transformation AWS::Serverless pour SAM.

Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      pythonLayerVersion: "101"
      stackName: !Ref "AWS::StackName"
      forwarderArn: "<ARN_FORWARDER>"
      service: "<SERVICE>" # Facultatif
      env: "<ENVIRONNEMENT>" # Facultatif

Renseignez les paramètres fictifs comme suit :

Remplacez <ARN_FORWARDER> par l’ARN du Forwarder (voir la documentation sur le Forwarder).
Remplacez <SERVICE> et <ENVIRONNEMENT> par votre service et votre environnement.

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

La macro CloudFormation Datadog transforme automatiquement le modèle CloudFormation généré par AWS CDK dans le but d’ajouter la bibliothèque Lambda Datadog à vos fonctions à l’aide de couches. Elle configure également vos fonctions de façon à envoyer des métriques, traces et logs à Datadog par l’intermédiaire du Forwarder Datadog.

Installation

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.

Instrumentation

Pour instrumenter la fonction, ajoutez la transformation DatadogServerless ainsi que CfnMapping à votre objet Stack dans votre application AWS CDK. Consultez l’exemple de code ci-dessous en Python (le fonctionnement est similaire dans d’autres langages).

from aws_cdk import core

class CdkStack(core.Stack):
  def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
    super().__init__(scope, id, **kwargs)
    self.add_transform("DatadogServerless")

    mapping = core.CfnMapping(self, "Datadog",
      mapping={
        "Parameters": {
          "pythonLayerVersion": "101",
          "forwarderArn": "<ARN_FORWARDER>",
          "stackName": self.stackName,
          "service": "<SERVICE>",  # Facultatif
          "env": "<ENVIRONNEMENT>",  # Facultatif
        }
      })

Renseignez les paramètres fictifs comme suit :

Remplacez <ARN_FORWARDER> par l’ARN du Forwarder (voir la documentation sur le Forwarder).
Remplacez <SERVICE> et <ENVIRONNEMENT> par votre service et votre environnement.

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

Mise à jour des paramètres

Ajoutez les paramètres suivants à votre fichier zappa_settings.json :

{
    "dev": {
        "layers": ["arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>"],
        "lambda_handler": "datadog_lambda.handler.handler",
        "aws_environment_variables": {
            "DD_LAMBDA_HANDLER": "handler.lambda_handler",
            "DD_TRACE_ENABLED": "true",
            "DD_FLUSH_TO_LOG": "true",
        },
    }
}

Remplacez les paramètres fictifs <AWS_REGION>, <RUNTIME> et <VERSION> dans l’ARN de couche par les valeurs appropriées. Les options RUNTIME disponibles sont Python38, Python39, Python310, Python311, Python312. La dernière VERSION disponible est 101. Exemple :
```
# For regular regions
arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python312:101

# For us-gov regions
arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python312:101
```
Si votre fonction Lambda est configurée de façon à utiliser la signature de code, ajoutez l’ARN du profil de signature de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) à la configuration de la signature de code de votre fonction.

Abonnement

Pour pouvoir envoyer des métriques, traces et logs à Datadog, abonnez la fonction Lambda du Forwarder Datadog à chaque groupe de logs de votre fonction.

Si ce n’est pas déjà fait, installez le Forwarder Datadog.
Abonnez le Forwarder Datadog aux groupes de logs de votre fonction.

Mise à jour du projet

Définissez vos variables d’environnement DD_TRACE_ENABLED et DD_FLUSH_TO_LOG sur "true" dans votre fichier config.json :

{
  "version": "2.0",
  "app_name": "hello-chalice",
  "stages": {
    "dev": {
      "api_gateway_stage": "api",
      "environment_variables": {
        "DD_TRACE_ENABLED": "true",
        "DD_FLUSH_TO_LOG": "true"
      }
    }
  }
}

Ajoutez datadog_lambda à votre fichier requirements.txt.

Enregistrez datadog_lambda_wrapper en tant que middleware dans 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'}

Si votre fonction Lambda est configurée de façon à utiliser la signature de code, ajoutez l’ARN du profil de signature de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) à la configuration de la signature de code de votre fonction.

Abonnement

Pour pouvoir envoyer des métriques, traces et logs à Datadog, abonnez la fonction Lambda du Forwarder Datadog à chaque groupe de logs de votre fonction.

Si ce n’est pas déjà fait, installez le Forwarder Datadog.
Abonnez le Forwarder Datadog aux groupes de logs de votre fonction.

Installation

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.

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.

Configuration

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

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

Si vous le souhaitez, ajoutez des tags service et env avec les valeurs appropriées dans votre fonction.

Abonnement

Pour pouvoir envoyer des métriques, traces et logs à Datadog, abonnez la fonction Lambda du Forwarder Datadog à chaque groupe de logs de votre fonction.

Installation

Vous pouvez installer la bibliothèque Lambda Datadog en tant que couche (option recommandée) 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.

Utilisation de la couche

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

# Pour les régions standard
arn:aws:lambda:<RÉGION_AWS>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>

# Pour les régions us-gov
arn:aws-us-gov:lambda:<RÉGION_AWS>:002406178527:layer:Datadog-<RUNTIME>:<VERSION>

Les options RUNTIME disponibles sont Python38, Python39, Python310, Python311, Python312. La dernière VERSION est 101. Exemple :

arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python312:101

Si votre fonction Lambda est configurée de façon à utiliser la signature de code, vous devez ajouter l’ARN du profil de signature de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) à la configuration de la signature de code de votre fonction avant de pouvoir ajouter la bibliothèque Lambda Datadog en tant que couche.

Utilisation du package

Installez datadog-lambda et ses dépendances localement dans le dossier du projet de votre fonction. Remarque : datadog-lambda dépend de ddtrace, qui a recours à des extensions natives ; ces extensions doivent donc être installées et compilées dans un environnement Linux. 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.

pip install datadog-lambda -t ./

Consultez la dernière version.

Configuration

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

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.
Définissez la variable d’environnement DD_TRACE_ENABLED sur true.
Définissez la variable d’environnement DD_FLUSH_TO_LOG sur true.
Vous pouvez également définir des tags service et env pour votre fonction avec des valeurs correspondantes.

Abonnement

Pour pouvoir envoyer des métriques, traces et logs à Datadog, abonnez la fonction Lambda du Forwarder Datadog à chaque groupe de logs de votre fonction.

Si ce n’est pas déjà fait, installez le Forwarder Datadog.
Abonnez le Forwarder Datadog aux groupes de logs de votre fonction.

Tag

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

Utilisation

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

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 :

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,
        timestamp=int (time.time()), # facultatif, doit correspondre aux 20 dernières minutes
        tags=['product:latte', 'order:online']
    )

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

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

Pour en savoir plus sur l’envoi de métriques custom, consultez cette page. Pour en savoir plus sur l’instrumentation personnalisée, consultez la documentation de l’APM Datadog relative à l’instrumentation personnalisée.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles: