Instrumentation du code C# 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 traçage à X-Ray, vous pouvez utiliser l'une des trois bibliothèques SDK suivantes :

• AWS Distro 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 .NET – Un kit SDK permettant de générer et d'envoyer des données de suivi à X-Ray.

• Powertools for AWS Lambda (.NET) — 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.

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

Les outils X-Ray et Powertools pour AWS Lambda les SDK 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 des solutions. 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).

Utilisation de Powertools pour AWS Lambda (.NET) 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 C# avec des modules Powertools pour AWS Lambda (.NET) intégrés à l'aide du. 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 :

• .NET 6 ou .NET 8

• AWS CLI version 2

• AWS SAM CLI version 1.75 ou ultérieure. Si vous disposez d'une ancienne version de la AWS SAM CLI, reportez-vous à la section Mise à niveau de la AWS SAM CLI.

Déployer un exemple d' AWS SAM application

1. Initialisez l'application à l'aide du TypeScript modèle Hello World.

   sam init --app-template hello-world-powertools-dotnet --name sam-app --package-type Zip --runtime dotnet6 --no-tracing

2. Créez l’application.

   cd sam-app && sam build

3. Déployez l’application.

   sam deploy --guided

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

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

6. Invoquez le point de terminaison de l’API :

   curl <URL_FROM_PREVIOUS_STEP>

   En cas de succès, vous obtiendrez cette réponse :

   {"message":"hello world"}

7. 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-20 23:05:16+08:00
     End time: 2023-02-20 23:05:16+08:00
     Reference Id: 0 - AWS::Lambda - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: [1]
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 2.814
     Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-pNjujb7mEoew - Edges: []
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 2.429
     Reference Id: 2 - (Root) AWS::ApiGateway::Stage - sam-app/Prod - Edges: [0]
      Summary_statistics:
        - total requests: 1
        - ok count(2XX): 1
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 2.839
     Reference Id: 3 - client - sam-app/Prod - Edges: [2]
      Summary_statistics:
        - total requests: 0
        - ok count(2XX): 0
        - error count(4XX): 0
        - fault count(5XX): 0
        - total response time: 0
   
   XRay Event [revision 3] at (2023-02-20T23:05:16.521000) with id (1-63f38c2c-270200bf1d292a442c8e8a00) and duration (2.877s)
    - 2.839s - sam-app/Prod [HTTP: 200]
      - 2.836s - Lambda [HTTP: 200]
    - 2.814s - sam-app-HelloWorldFunction-pNjujb7mEoew [HTTP: 200]
    - 2.429s - sam-app-HelloWorldFunction-pNjujb7mEoew
      - 0.230s - Initialization
      - 2.389s - Invocation
        - 0.600s - ## FunctionHandler
          - 0.517s - Get Calling IP
      - 0.039s - Overhead

8. 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 du kit SDK X-Ray pour instrumenter vos fonctions .NET

Vous pouvez instrumenter le code de gestionnaire pour enregistrer les métadonnées et suivre les appels en aval. Pour enregistrer les détails des appels que votre fonction effectue vers d'autres ressources et services, utilisez le Kit SDK AWS X-Ray pour .NET. Pour obtenir ce kit SDK, ajoutez les packages AWSXRayRecorder à votre fichier de projet.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
    <AWSProjectType>Lambda</AWSProjectType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.SQSEvents" Version="2.1.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.Json" Version="2.1.0" />
    <PackageReference Include="AWSSDK.Core" Version="3.7.103.24" />
    <PackageReference Include="AWSSDK.Lambda" Version="3.7.104.3" />
    <PackageReference Include="AWSXRayRecorder.Core" Version="2.13.0" />
    <PackageReference Include="AWSXRayRecorder.Handlers.AwsSdk" Version="2.11.0" />
  </ItemGroup>
</Project>

Il existe une gamme de packages Nuget qui fournissent une instrumentation automatique pour les AWS SDK, Entity Framework et les requêtes HTTP. Pour connaître l'ensemble des options de configuration, reportez-vous à kit SDK AWS X-Ray pour .NET dans le Guide du développeur AWS X-Ray .

Une fois que vous avez ajouté les packages Nuget de votre choix, configurez l'auto-instrumentation. La meilleure pratique consiste à effectuer cette configuration en dehors de la fonction du gestionnaire de votre fonction. Cela vous permet de tirer parti de la réutilisation de l'environnement d'exécution afin d'améliorer les performances de votre fonction. Dans l'exemple de code suivant, la RegisterXRayForAllServices méthode est appelée dans le constructeur de fonctions pour ajouter de l'instrumentation à tous les appels du AWS SDK.

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        // Add auto instrumentation for all AWS SDK calls
        // It is important to call this method before initializing any SDK clients
        AWSSDKHandler.RegisterXRayForAllServices();
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord)
        };
    }
}

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

1. Ouvrez la page Functions (Fonctions) de la console Lambda.

2. Choisissez une fonction.

3. Choisissez Configuration, puis choisissez Outils de surveillance et d'opérations.

4. Choisissez Modifier.

5. Sous X-Ray, activer/désactiver Active tracing (Traçage actif).

6. Choisissez Enregistrer.

Activation du suivi avec l'API Lambda

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

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

L'exemple de AWS CLI commande 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 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 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

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.

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.

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.

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 .NET 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 AWS X-Ray Tarification.