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

Instrumentation du code Python dans AWS Lambda

Lambda s'intègre pour vous aider AWS X-Ray à 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 suivi à X-Ray, vous pouvez utiliser l'une des trois SDK bibliothèques suivantes :

AWS Distro for OpenTelemetry (ADOT) — Une distribution sécurisée, prête pour la production et AWS prise en charge du (). OpenTelemetry OTel SDK
Kit SDK AWS X-Ray pour Python— Et SDK pour générer et envoyer des données de trace à X-Ray.
Powertools for AWS Lambda (Python) — Une boîte à outils pour les développeurs permettant de mettre en œuvre les meilleures pratiques sans serveur et d'accroître la rapidité des développeurs.

Chacune d'entre elles SDKs propose 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

Les outils X-Ray et Powertools pour AWS Lambda SDKs 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 les instruments de traçage qui collectent plus de données en général, mais peuvent 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 Choosing between the AWS Distro for Open Telemetry and X-Ray. SDKs

Sections

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

Utilisation de Powertools pour AWS Lambda (Python) et 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 du AWS SAM. Cette application implémente un API backend de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Il se compose d'un point de terminaison Amazon API Gateway et d'une fonction Lambda. Lorsque vous envoyez une GET demande 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 SAM CLIversion 1.75 ou ultérieure. Si vous possédez une ancienne version du AWS SAM CLI, consultez la section Mise à niveau du AWS SAM CLI.

Déployer un exemple d' AWS SAM application

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 le code URL de l'application déployée :


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

Appelez le API point de terminaison :
```
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 API point de terminaison public accessible via 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. Vous ne pouvez pas configurer la fréquence d'échantillonnage des rayons X pour vos fonctions.

Utilisation de Powertools pour AWS Lambda (Python) et 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 du AWS CDK. Cette application implémente un API backend de base et utilise Powertools pour émettre des journaux, des métriques et des traces. Il se compose d'un point de terminaison Amazon API Gateway et d'une fonction Lambda. Lorsque vous envoyez une GET demande 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
AWS SAM CLIversion 1.75 ou ultérieure. Si vous possédez une ancienne version du AWS SAM CLI, consultez la section Mise à niveau du AWS SAM CLI.

Déployer un exemple d' AWS CDK application

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 définit la durée de conservation des journaux à une semaine, et le constructeur 1, qui crée le ApiGatewayv. REST API


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 le code URL de l'application déployée :


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

Appelez le API point de terminaison :
```
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 API point de terminaison public accessible via Internet. Nous vous recommandons de supprimer le point de terminaison après un test.
```
cdk destroy
```

Utilisation ADOT pour instrumenter vos fonctions Python

ADOTfournit 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. OTel SDK 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 deOTel. Pour plus d'informations, consultez la section Configuration personnalisée du ADOT collecteur sur Lambda dans la ADOT documentation.

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

Utiliser le X-Ray SDK 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 leSDK, ajoutez le aws-xray-sdk package 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 AWS SDK les clients en appliquant le aws_xray_sdk.core module à la boto3 bibliothèque.

Exemple function — Suivi d'un AWS SDK 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)))
  ...

Après avoir ajouté les dépendances correctes et apporté les modifications de code nécessaires, activez le suivi dans la configuration de votre fonction via la console Lambda ou le. 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 Save (Enregistrer).

Activation du traçage avec le Lambda API

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

L'exemple de AWS CLI commande suivant permet d'activer 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 traçage avec AWS CloudFormation

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

Exemple function-inline.yml – Configuration du suivi


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

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

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. Dans le cas contraire, 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 montre une application dotée de 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 du premier et utilise le AWS SDK pour appeler X-Ray, Amazon Simple Storage Service (Amazon S3) et Amazon CloudWatch Logs.

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

Dans X-Ray, un suivi enregistre des informations sur une demande traitée par un ou plusieurs services. Lambda enregistre 2 segments par trace, ce qui crée deux nœuds sur le graphe de service. L'image suivante met en évidence ces deux nœuds :

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 my-function, mais l'un a une origine de AWS::Lambda et l'autre a une origine deAWS::Lambda::Function. Si le AWS::Lambda segment affiche une erreur, cela signifie que le service Lambda a rencontré un problème. Si le AWS::Lambda::Function segment affiche une erreur, cela signifie que votre fonction a rencontré un problème.

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

Cet exemple développe le AWS::Lambda::Function segment pour afficher ses trois sous-segments.

Note

AWS met actuellement en œuvre des modifications du service Lambda. En raison de ces modifications, vous pouvez constater des différences mineures entre la structure et le contenu des messages du journal système et des segments de trace émis par les différentes fonctions Lambda de votre ordinateur. Compte AWS

L'exemple de trace présenté ici illustre le segment de fonction à l'ancienne. Les différences entre les segments de style ancien et nouveau sont décrites dans les paragraphes suivants.

Ces modifications seront mises en œuvre au cours des prochaines semaines, et toutes les fonctions, Régions AWS sauf en Chine et dans les GovCloud régions, passeront à l'utilisation du nouveau format des messages de journal et des segments de trace.

Le segment de fonction à l'ancienne contient les sous-segments suivants :

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.

Le segment de fonction du nouveau style ne contient pas de Invocation sous-segment. Au lieu de cela, les sous-segments clients sont rattachés directement au segment fonctionnel. Pour plus d'informations sur la structure des segments de fonction de l'ancien et du nouveau style, consultezComprendre les suivis X-Ray.

Vous pouvez également instrumenter HTTP les clients, enregistrer SQL des requêtes 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 le X-Ray Tracing gratuitement chaque mois jusqu'à une certaine limite dans le cadre du niveau AWS gratuit. Au-delà de ce seuil, X-Ray facture le stockage et la récupération du suivi. Pour en savoir plus, consultez Pricing AWS X-Ray (Tarification).

Stockage des dépendances d'exécution dans une couche (X-RaySDK)

Si vous utilisez le X-Ray SDK pour instrumenter votre code de fonction chez les AWS SDK clients, votre package de déploiement peut devenir assez volumineux. Pour éviter de télécharger les dépendances d'exécution chaque fois que vous mettez à jour le code de votre fonction, empaquetez le X-Ray SDK 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

Test

Création avec Ruby