Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour le traçage Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS CDK pour le traçage Interprétation d'un suivi X-Ray

TypeScript Code de suivi 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 Noce.js : un kit SDK permettant de générer et d'envoyer des données de suivi à X-Ray.
Powertools for AWS Lambda (TypeScript) — 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

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

Sections

Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour le traçage
Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS CDK pour le traçage
Interprétation d'un suivi X-Ray

Utilisation de Powertools pour AWS Lambda (TypeScript) et AWS SAM pour le traçage

Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World avec des modules Powertools for AWS Lambda (TypeScript) intégrés à l'aide duAWS 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 :

Node.js 18.x ou version ultérieure
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 TypeScript modèle Hello World.


sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs18.x --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 <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 :


XRay Event [revision 1] at (2023-01-31T11:29:40.527000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.483s)
  - 0.425s - sam-app/Prod [HTTP: 200]
    - 0.422s - Lambda [HTTP: 200]
  - 0.406s - sam-app-HelloWorldFunction-Xyzv11a1bcde [HTTP: 200]
  - 0.172s - sam-app-HelloWorldFunction-Xyzv11a1bcde
    - 0.179s - Initialization
    - 0.112s - Invocation
      - 0.052s - ## app.lambdaHandler
        - 0.001s - ### MySubSegment
    - 0.059s - 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 (TypeScript) et AWS CDK pour le traçage

Suivez les étapes ci-dessous pour télécharger, créer et déployer un exemple d' TypeScript application Hello World avec des modules Powertools for AWS Lambda (TypeScript) intégrés à l'aide duAWS 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 :

Node.js 18.x ou version ultérieure
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 Cloud Development Kit (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 typescript
```
Ajoutez le pack @types/aws-lambda en tant que dépendance de développement.
```
npm install -D @types/aws-lambda
```

Installez l'utilitaire Powertools Tracer.


npm install @aws-lambda-powertools/tracer

Ouvrez le répertoire lib. Vous devriez voir un fichier appelé hello-world-stack.ts. Créez deux nouveaux fichiers dans ce répertoire : hello-world.function.ts et hello-world.ts.

Ouvrez hello-world.function.ts et ajoutez le code suivant au fichier. Il s'agit du code de la fonction Lambda.


import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Tracer } from '@aws-lambda-powertools/tracer';
const tracer = new Tracer();

export const handler = async (event: APIGatewayEvent, context: Context): Promise<APIGatewayProxyResult> => {
  // Get facade segment created by Lambda
  const segment = tracer.getSegment();

  // Create subsegment for the function and set it as active
  const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
  tracer.setSegment(handlerSegment);

  // Annotate the subsegment with the cold start and serviceName
  tracer.annotateColdStart();
  tracer.addServiceNameAnnotation();

  // Add annotation for the awsRequestId
  tracer.putAnnotation('awsRequestId', context.awsRequestId);
  // Create another subsegment and set it as active
  const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
  tracer.setSegment(subsegment);
  let response: APIGatewayProxyResult = {
    statusCode: 200,
    body: JSON.stringify({
      message: 'hello world',
    }),
  };
  // Close subsegments (the Lambda one is closed automatically)
  subsegment.close(); // (### MySubSegment)
  handlerSegment.close(); // (## index.handler)

  // Set the facade segment as active again (the one created by Lambda)
  tracer.setSegment(segment);
  return response;
};

Ouvrez hello-world.ts et ajoutez le code suivant au fichier. Il contient la NodejsFunction construction 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. Il inclut également la LambdaRestApi construction qui crée l'API REST.


import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
import { CfnOutput } from 'aws-cdk-lib';
import { Tracing } from 'aws-cdk-lib/aws-lambda';

export class HelloWorld extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    const helloFunction = new NodejsFunction(this, 'function', {
      environment: {
        POWERTOOLS_SERVICE_NAME: 'helloWorld',
      },
      tracing: Tracing.ACTIVE,
    });
    const api = new LambdaRestApi(this, 'apigw', {
      handler: helloFunction,
    });
    new CfnOutput(this, 'apiUrl', {
      exportName: 'apiUrl',
      value: api.url,
    });
  }
}

Ouvrez hello-world-stack.ts. C'est le code qui définit votre pile de AWS CDK. Remplacez le code par ce qui suit :


import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
  
export class HelloWorldStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    new HelloWorld(this, 'hello-world');
  }
}

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[?ExportName==`apiUrl`].OutputValue' --output text

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"}
```

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


sam traces

La sortie de la trace ressemble à ceci :


XRay Event [revision 1] at (2023-01-31T11:50:06.997000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.449s)
  - 0.350s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde [HTTP: 200]
  - 0.157s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde
    - 0.169s - Initialization
    - 0.058s - Invocation
      - 0.055s - ## index.handler
        - 0.000s - ### MySubSegment
    - 0.099s - 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
```

Interprétation d'un suivi X-Ray

Une fois que vous avez configuré le suivi actif, vous pouvez observer des demandes spécifiques via votre application. La mappe de trace X-Ray fournit des informations sur votre application et tous ses composants. L'exemple suivant montre une trace à partir de l'exemple d'application :

Mappage du service X-Ray pour l'exemple d'application

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

Journalisation

Création avec Python