Utilisation de Powertools pour AWS Lambda (Python) et d'AWS SAM pour le traçage Utilisation de Powertools pour AWS Lambda (Python) et de AWS CDK pour le traçage Utilisation d'ADOT pour instrumenter vos fonctions python Utilisation du kit SDK X-Ray pour instrumenter vos fonctions Python Activation du suivi avec la console Lambda Activation du suivi avec l'API Lambda Activation du suivi avec AWS CloudFormation Interprétation d'un suivi X-Ray Stockage des dépendances d'exécution dans une couche (kit SDK X-Ray)

Instrumentation du code Python dans AWS Lambda

Lambda s'intègre avec AWS X-Ray pour vous aider à suivre, déboguer et optimiser les applications Lambda. Vous pouvez utiliser X-Ray pour suivre une demande lorsque celle-ci parcourt les ressources de votre application, qui peuvent inclure des fonctions Lambda et d'autres services AWS.

Pour envoyer des données de traçage à X-Ray, vous pouvez utiliser l'une des trois bibliothèques SDK suivantes :

AWSDistro for OpenTelemetry (ADOT) — Une distribution sécurisée, prête pour la production et prise AWS en charge du SDK (OTel). OpenTelemetry
Kit SDK AWS X-Ray pour Python – Un kit SDK permettant de générer et d'envoyer des données de suivi à X-Ray.
Powertools pour AWS Lambda (Python) : une boîte à outils pour développeurs permettant de mettre en œuvre les bonnes pratiques en matière de sans serveur et d'augmenter la rapidité des développeurs.

Chacun des kits SDK offre des moyens d'envoyer vos données de télémétrie au service X-Ray. Vous pouvez ensuite utiliser X-Ray pour afficher, filtrer et avoir un aperçu des métriques de performance de votre application, afin d'identifier les problèmes et les occasions d'optimiser votre application.

Important

X-Ray et Powertools pour les kits SDK AWS Lambda font partie d'une solution d'instrumentation étroitement intégrée proposée par AWS. Les couches ADOT Lambda font partie d'une norme industrielle pour l'instrumentation de traçage qui collecte plus de données en général, mais qui peut ne pas convenir à tous les cas d'utilisation. Vous pouvez implémenter le end-to-end traçage dans X-Ray en utilisant l'une ou l'autre solution. Pour en savoir plus sur le choix entre les deux, consultez Choix entre les kits SDK AWS Distro for OpenTelemetry et X-Ray (français non garanti).

Sections

Utilisation de Powertools pour AWS Lambda (Python) et d'AWS SAM pour le traçage
Utilisation de Powertools pour AWS Lambda (Python) et de AWS CDK pour le traçage
Utilisation d'ADOT pour instrumenter vos fonctions python
Utilisation du kit SDK X-Ray pour instrumenter vos fonctions Python
Activation du suivi avec la console Lambda
Activation du suivi avec l'API Lambda
Activation du suivi avec AWS CloudFormation
Interprétation d'un suivi X-Ray
Stockage des dépendances d'exécution dans une couche (kit SDK X-Ray)

Utilisation de Powertools pour AWS Lambda (Python) et d'AWS SAM pour le traçage

Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d'application Hello World Python avec des modules Powertools pour AWS Lambda (Python) intégrés à l'aide d'AWS SAM. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une requête GET au point de terminaison API Gateway, la fonction Lambda appelle, envoie des journaux et des métriques au format métrique intégré à CloudWatch, et envoie des traces à. AWS X-Ray La fonction renvoie un message hello world.

Prérequis

Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :

Python 3.9
AWS CLI version 2
CLI AWS SAM version 1.75 ou ultérieure. Si vous avez une version antérieure de la CLI AWS SAM, consultez Mise à niveau de la CLI AWS SAM.

Déployer un exemple d’application AWS SAM

Initialisez l’application à l’aide du modèle Hello World Python.


sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.9 --no-tracing

Créez l’application.
```
cd sam-app && sam build
```
Déployez l’application.
```
sam deploy --guided
```
Suivez les invites à l’écran. Appuyez sur Enter pour accepter les options par défaut fournies dans l’expérience interactive.

Note
Car l'autorisation n'a HelloWorldFunction peut-être pas été définie, est-ce que ça va ? , assurez-vous de participery.

Obtenez l’URL de l’application déployée :


aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

Invoquez le point de terminaison de l’API :
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
En cas de succès, vous obtiendrez cette réponse :
```
{"message":"hello world"}
```

Pour obtenir les traces de la fonction, exécutez sam traces.


sam traces

La sortie de la trace ressemble à ceci :


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-02-03 14:59:50+00:00
  Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.924
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.016
  Reference Id: 2 - client - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [0]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 1] at (2023-02-03T14:59:50.204000) with id (1-63dd2166-434a12c22e1307ff2114f299) and duration (0.924s)
 - 0.924s - sam-app-HelloWorldFunction-YBg8yfYtOc9j [HTTP: 200]
 - 0.016s - sam-app-HelloWorldFunction-YBg8yfYtOc9j
   - 0.739s - Initialization
   - 0.016s - Invocation
     - 0.013s - ## lambda_handler
       - 0.000s - ## app.hello
   - 0.000s - Overhead

Il s'agit d'un point de terminaison d'API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
sam delete
```

X-Ray ne trace pas toutes les requêtes vers votre application. X-Ray applique un algorithme d'échantillonnage pour s'assurer que le suivi est efficace, tout en fournissant un échantillon représentatif de toutes les demandes. Le taux d'échantillonnage est 1 demande par seconde et 5 % de demandes supplémentaires.

Note

Vous ne pouvez pas configurer ce taux d'échantillonnage X-Ray pour vos fonctions.

Utilisation de Powertools pour AWS Lambda (Python) et de AWS CDK pour le traçage

Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d'application Hello World Python avec des modules Powertools pour AWS Lambda (Python) intégrés à l'aide d'AWS CDK. Cette application met en œuvre un backend API de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Elle se compose d’un point de terminaison Amazon API Gateway et d’une fonction Lambda. Lorsque vous envoyez une requête GET au point de terminaison API Gateway, la fonction Lambda appelle, envoie des journaux et des métriques au format métrique intégré à CloudWatch, et envoie des traces à. AWS X-Ray La fonction renvoie un message hello world.

Prérequis

Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :

Python 3.9
AWS CLI version 2
AWS CDK version 2
CLI AWS SAM version 1.75 ou ultérieure. Si vous avez une version antérieure de la CLI AWS SAM, consultez Mise à niveau de la CLI AWS SAM.

Déployer un exemple d’application AWS CDK

Créez un répertoire de projets pour votre nouvelle application.
```
mkdir hello-world
cd hello-world
```
Initialisez l’application.
```
cdk init app --language python
```
Installez les dépendances de Python.
```
pip install -r requirements.txt
```
Créez un répertoire lambda_function dans le dossier racine.
```
mkdir lambda_function
cd lambda_function
```

Créez un fichier app.py et ajoutez-y le code suivant. Il s’agit du code de la fonction Lambda.


from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools import Logger
from aws_lambda_powertools import Tracer
from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit

app = APIGatewayRestResolver()
tracer = Tracer()
logger = Logger()
metrics = Metrics(namespace="PowertoolsSample")

@app.get("/hello")
@tracer.capture_method
def hello():
    # adding custom metrics
    # See: https://docs.powertools.aws.dev/lambda-python/latest/core/metrics/
    metrics.add_metric(name="HelloWorldInvocations", unit=MetricUnit.Count, value=1)

    # structured log
    # See: https://docs.powertools.aws.dev/lambda-python/latest/core/logger/
    logger.info("Hello world API - HTTP 200")
    return {"message": "hello world"}

# Enrich logging with contextual information from Lambda
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
# Adding tracer
# See: https://docs.powertools.aws.dev/lambda-python/latest/core/tracer/
@tracer.capture_lambda_handler
# ensures metrics are flushed upon request completion/failure and capturing ColdStart metric
@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

Ouvrez le répertoire hello_world. Vous devriez voir un fichier nommé hello_world_stack.py.
```
cd ..
cd hello_world
```

Ouvrez hello_world_stack.py et ajoutez le code suivant au fichier. Il contient le constructeur Lambda, qui crée la fonction Lambda, configure les variables d'environnement pour Powertools et fixe la durée de conservation des journaux à une semaine, et le constructeur ApiGatewayv 1, qui crée l'API REST.


from aws_cdk import (
    Stack,
    aws_apigateway as apigwv1,
    aws_lambda as lambda_,
    CfnOutput,
    Duration
)
from constructs import Construct

class HelloWorldStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Powertools Lambda Layer
        powertools_layer = lambda_.LayerVersion.from_layer_version_arn(
            self,
            id="lambda-powertools",
            # At the moment we wrote this example, the aws_lambda_python_alpha CDK constructor is in Alpha, o we use layer to make the example simpler
            # See https://docs.aws.amazon.com/cdk/api/v2/python/aws_cdk.aws_lambda_python_alpha/README.html
            # Check all Powertools layers versions here: https://docs.powertools.aws.dev/lambda-python/latest/#lambda-layer
            layer_version_arn=f"arn:aws:lambda:{self.region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:21"
        )

        function = lambda_.Function(self,
            'sample-app-lambda',
            runtime=lambda_.Runtime.PYTHON_3_9,
            layers=[powertools_layer],
            code = lambda_.Code.from_asset("./lambda_function/"),
            handler="app.lambda_handler",
            memory_size=128,
            timeout=Duration.seconds(3),
            architecture=lambda_.Architecture.X86_64,
            environment={
                "POWERTOOLS_SERVICE_NAME": "PowertoolsHelloWorld",
                "POWERTOOLS_METRICS_NAMESPACE": "PowertoolsSample",
                "LOG_LEVEL": "INFO"
            }
        )

        apigw = apigwv1.RestApi(self, "PowertoolsAPI", deploy_options=apigwv1.StageOptions(stage_name="dev"))

        hello_api = apigw.root.add_resource("hello")
        hello_api.add_method("GET", apigwv1.LambdaIntegration(function, proxy=True))

        CfnOutput(self, "apiUrl", value=f"{apigw.url}hello")

Déployez votre application.
```
cd ..
cdk deploy
```

Obtenez l’URL de l’application déployée :


aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`apiUrl`].OutputValue' --output text

Invoquez le point de terminaison de l’API :
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
En cas de succès, vous obtiendrez cette réponse :
```
{"message":"hello world"}
```

Pour obtenir les traces de la fonction, exécutez sam traces.


sam traces

La sortie des traces ressemble à ceci :


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-02-03 14:59:50+00:00
  Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.924
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.016
  Reference Id: 2 - client - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [0]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 1] at (2023-02-03T14:59:50.204000) with id (1-63dd2166-434a12c22e1307ff2114f299) and duration (0.924s)
 - 0.924s - sam-app-HelloWorldFunction-YBg8yfYtOc9j [HTTP: 200]
 - 0.016s - sam-app-HelloWorldFunction-YBg8yfYtOc9j
   - 0.739s - Initialization
   - 0.016s - Invocation
     - 0.013s - ## lambda_handler
       - 0.000s - ## app.hello
   - 0.000s - Overhead

Il s'agit d'un point de terminaison d'API public accessible par Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
cdk destroy
```

Utilisation d'ADOT pour instrumenter vos fonctions python

ADOT fournit des couches Lambda entièrement gérées qui regroupent tout ce dont vous avez besoin pour collecter des données de télémétrie à l'aide du kit SDK OTel. En consommant cette couche, vous pouvez instrumenter vos fonctions Lambda sans avoir à modifier le code de fonction. Vous pouvez également configurer votre couche pour effectuer une initialisation personnalisée d'OTel. Pour de plus amples informations, veuillez consulter Configuration personnalisée pour ADOT Collector sur Lambda dans la documentation ADOT.

Pour les exécutions python, vous pouvez ajouter leAWS couche Lambda gérée pour ADOT Pythonpour instrumenter automatiquement vos fonctions. Cette couche fonctionne à la fois pour les architectures arm64 et x86_64. Pour des instructions détaillées sur la façon d'ajouter cette couche, consultez AWSDistro for OpenTelemetry Lambda Support for Python dans la documentation ADOT.

Utilisation du kit SDK X-Ray pour instrumenter vos fonctions Python

Pour enregistrer des détails sur les appels effectués par votre fonction Lambda à d'autres ressources de votre application, vous pouvez également utiliser le Kit SDK AWS X-Ray pour Python. Pour obtenir ce kit SDK, ajoutez le package aws-xray-sdk aux dépendances de votre application.

Exemple requirements.txt


jsonpickle==1.3
aws-xray-sdk==2.4.3

Dans votre code de fonction, vous pouvez instrumenter le kit SDK AWS clients en corrigeant le boto3 bibliothèque avec le module aws_xray_sdk.core.

Exemple fonction – Tracer un kit SDK AWS client


import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

logger = logging.getLogger()
logger.setLevel(logging.INFO)
patch_all()

client = boto3.client('lambda')
client.get_account_settings()

def lambda_handler(event, context):
    logger.info('## ENVIRONMENT VARIABLES\r' + jsonpickle.encode(dict(**os.environ)))
  ...

Une fois que vous avez ajouté les bonnes dépendances et effectué les modifications de code nécessaires, activez le suivi dans la configuration de votre fonction via la console Lambda ou l'API.

Activation du suivi avec la console Lambda

Pour activer/désactiver le traçage actif sur votre fonction Lambda avec la console, procédez comme suit :

Pour activer le traçage actif

Ouvrez la page Functions (Fonctions) de la console Lambda.
Choisissez une fonction.
Choisissez Configuration, puis choisissez Outils de surveillance et d'opérations.
Choisissez Modifier.
Sous X-Ray, activer/désactiver Active tracing (Traçage actif).
Choisissez Enregistrer.

Activation du suivi avec l'API Lambda

Configurez le suivi sur votre fonction Lambda avec le AWS CLI ou le kit SDK AWS, utilisez les opérations d'API suivantes :

L'exemple de commande AWS CLI suivant active le suivi actif sur une fonction nommée my-function.


aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

Le mode de suivi fait partie de la configuration spécifique de la version lorsque vous publiez une version de votre fonction. Vous ne pouvez pas modifier le mode de suivi sur une version publiée.

Activation du suivi avec AWS CloudFormation

Pour activer le suivi d'une ressource AWS::Lambda::Function dans un modèle AWS CloudFormation, utilisez la propriété TracingConfig.

Exemple function-inline.yml – Configuration du suivi


Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Pour une ressource AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function, utilisez la propriété Tracing.

Exemple template.yml – Configuration du suivi


Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interprétation d'un suivi X-Ray

Votre fonction a besoin d'une autorisation pour charger des données de suivi vers X-Ray. Lorsque vous activez le suivi actif dans la console Lambda, Lambda ajoute les autorisations requises au rôle d'exécution de votre fonction. Sinon, ajoutez la AWSXRayDaemonWriteAccesspolitique au rôle d'exécution.

Une fois que vous avez configuré le suivi actif, vous pouvez observer des demandes spécifiques via votre application. Le graphique de services X-Ray affiche des informations sur votre application et tous ses composants. L'exemple suivant de l'exemple d'application processeur d'erreurs montre une application avec deux fonctions. La fonction principale traite les événements et renvoie parfois des erreurs. La deuxième fonction située en haut traite les erreurs qui apparaissent dans le groupe de journaux de la première et utilise le AWS SDK pour appeler X-Ray, Amazon Simple Storage Service (Amazon S3) et Amazon Logs. CloudWatch

Diagramme qui montre deux applications distinctes et leurs cartes de service respectives dans X-Ray

Note

Vous ne pouvez pas configurer ce taux d'échantillonnage X-Ray pour vos fonctions.

Lors de l'utilisation du traçage actif, Lambda enregistre deux segments par suivi, ce qui a pour effet de créer deux nœuds sur le graphique du service. L'image suivante indique en surbrillance les deux nœuds pour la fonction principale de l'exemple d'application du processeur d'erreurs.

Cartographie du service X-Ray avec une seule fonction.

Le premier nœud sur la gauche représente le service Lambda qui reçoit la demande d'invocation. Le deuxième nœud représente votre fonction Lambda spécifique. L'exemple suivant illustre une trace avec ces deux segments. Les deux sont nommés mon-fonction, mais l'un a pour origine AWS::Lambda et l'autre a pour origine AWS::Lambda::Function.

Trace de X-Ray qui montre la latence sur chaque sous-segment d'une invocation Lambda spécifique.

Cet exemple développe le segment de fonction pour afficher ses trois sous-segments :

Initialization (Initialisation) : représente le temps passé à charger votre fonction et à exécuter le code d'initialisation. Ce sous-segment apparaît pour le premier événement traité par chaque instance de votre fonction.
Invocation – Représente le temps passé à exécuter votre code de gestionnaire.
Overhead (Travail supplémentaire) – Représente le temps que le fichier d'exécution Lambda passe à se préparer à gérer l'événement suivant.

Vous pouvez également utiliser des clients HTTP, enregistrer des requêtes SQL et créer des sous-segments personnalisés avec des annotations et des métadonnées. Pour plus d'informations, consultez Kit SDK AWS X-Ray pour Python dans le AWS X-Ray Guide du développeur.

Tarification

Vous pouvez utiliser gratuitement le traçage par X-Ray chaque mois jusqu'à une certaine limite dans le cadre de l'offre gratuite AWS. Au-delà de ce seuil, X-Ray facture le stockage et la récupération du suivi. Pour en savoir plus, consultez AWS X-Ray Tarification.

Stockage des dépendances d'exécution dans une couche (kit SDK X-Ray)

Si vous utilisez le kit SDK X-Ray pour instrumenter des clients de kit SDK AWS avec votre code de fonction, votre package de déploiement peut devenir assez volumineux. Pour éviter de charger des dépendances d'environnement d'exécution chaque fois que vous mettez à jour votre code de fonction, empaquetez le kit SDK X-Ray dans une couche Lambda.

L'exemple suivant montre une ressource AWS::Serverless::LayerVersion qui stocke le Kit SDK AWS X-Ray pour Python.

Exemple template.yml : couche de dépendances


Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-python-lib
      Description: Dependencies for the blank-python sample app.
      ContentUri: package/.
      CompatibleRuntimes:
        - python3.8

Avec cette configuration, vous ne mettez à jour les fichiers de couche de bibliothèque que si vous modifiez vos dépendances d'exécution. Étant donné que le package de déploiement de la fonction contient uniquement votre code, cela peut contribuer à réduire les temps de chargement.

La création d'une couche de dépendances nécessite des modifications de génération pour créer l'archive des couches avant le déploiement. Pour un exemple fonctionnel, consultez l'exemple d'application blank-python.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Erreurs

Création avec Ruby