Le Blog Amazon Web Services

Utiliser le suivi actif AWS X-Ray avec Amazon EventBridge

AWS X-Ray permet aux développeurs de débugger et analyser leurs applications distribuées. Ce service est utile pour tracer des transactions au travers d’architectures microservices, comme celles habituellement implémentées par les applications serverless. Amazon EventBridge permet de router des évènements entre différents services AWS, des applications intégrées de type SaaS (software as a service), et vos propres applications. L’intérêt est ici de découpler les applications pour construire des architectures plus simples à maintenir et à étendre.

EventBridge supporte la propagation du contexte des traces pour X-Ray, ce qui rend plus facile le suivi des transactions aux travers d’architectures basées sur des évènements. Potentiellement, cela permet de suivre une requête particulière depuis la production de l’évènement jusqu’à son traitement final par un consommateur, dans le cadre d’applications découplées où le consommateur n’a aucune information sur la manière dont l’évènement a été produit.

Cet article explore comment utiliser X-Ray avec EventBridge et présente l’implémentation du suivi au travers de l’exemple disponible sur ce dépôt GitHub.

Fonctionnement

X-Ray fonctionne en ajoutant aux requêtes un en-tête pour le suivi, qui est un identifiant unique. Dans le cas d’une application serverless développée avec plusieurs services AWS, X-Ray peut grouper les interactions entre les services dans une seule trace. X-Ray peut alors fournir une carte des services représentant le flux des transactions ou encore les données brutes d’une trace :

X-Ray map

Lorsque des évènements sont envoyés à EventBridge, le service utilise des règles pour déterminer les cibles vers lesquelles ils seront acheminés. N’importe quel évènement envoyé à un bus d’évènement grâce à l’API PutEvents peut prendre en charge la propagation du contexte de la trace, l’en-tête de la trace est fournie sous la forme de méta-donnée interne. L’en-tête lui-même n’est pas disponible dans l’évènement envoyé à la cible. Pour les développeurs qui utilisent l’archivage d’EventBridge, cela signifie que l’ID de la trace n’est pas disponible lorsqu’ils sont rejoués, ni pour les évènements envoyés sur une file d’attente de lettres mortes (DLQ, dead-letter queue).

Activation des traces avec EventBridge

L’activation des traces par l’ajout de l’en-tête ne nécessite aucune modification de la structure des évènements. Au lieu de cela, il suffit d’encapsuler le client du SDK AWS dans un appel à AWSXRay.captureAWSClient et de donner les permissions IAM pour autoriser le suivi via X-Ray. X-Ray peut alors instrumenter automatiquement les appels avec l’en-tête X-Amzn-Trace-Id.

Dans le cas du SDK AWS JavaScript, cela nécessite donc de modifier l’instanciation du client EventBridge: sans le tracing, la déclaration est a suivante :

const AWS = require('aws-sdk')
const eventBridge = new AWS.EventBridge()

Pour activer le tracing, le code devient :

const AWSXRay = require('aws-xray-sdk')
const AWS = AWSXRay.captureAWS(require('aws-sdk'))
const eventBridge = new AWS.EventBridge()

Les interactions avec le client EventBridge restent les mêmes, mais les appels seront dorénavant instrumentés par X-Ray. La fonction PutEvents de l’API est alors utilisée pour envoyer des évènements au bus d’évènements programmatiquement, comme dans l’exemple ci-dessous, dans le cadre d’une fonction AWS Lambda Node.js :

const AWSXRay = require('aws-xray-sdk')
const AWS = AWSXRay.captureAWS(require('aws-sdk'))
const eventBridge = new AWS.EventBridge()
exports.handler = async (event) => {
    
    let myDetail = { "name": "Alice" }
    
    const myEvent = { 
        Entries: [{
            Detail: JSON.stringify({ myDetail }),
            DetailType: 'myDetailType',
            Source: 'myApplication',
            Time: new Date
        }]}
    
    // Send to EventBridge
    const result = await eventBridge.putEvents(myEvent).promise()
    
    // Log the result
    console.log('Result: ', JSON.stringify(result, null, 2))
}

Il est aussi possible de définir un en-tête de suivi personnalisé avec le nouvel attribut TraceHeader du modèle PutEventsRequestEntry de l’API . La valeur unique fournie remplace tout en-tête de suivi déjà présent dans les en-têtes HTTP. Cette valeur est aussi validée par X-Ray et supprimée si la validation échoue. Le Guide du développeur X-Ray fournit plus de détails sur la génération d’en-têtes de suivi valides.

Déployer l’application

L’application fournie en exemple est composée d’un microservice webhook pour publier des évènements et d’un microservice cible pour les traiter. Les évènement créés comportent un attribut target pour déterminer quelle cible doit recevoir l’évènement.

Webhook events

Le déploiement de ces microservices nécessite l’installation du CLI AWS SAM et de Node.js 16.x, les instructions de déploiement étant disponibles sur le dépôt GitHub.

EventBridge peut acheminer les évènements sur un large éventail de services cibles AWS. Les cibles qui supportent le suivi actif pour X-Ray peuvent créer des traces complètes à partir de l’évènement source. Ces services sont AWS Lambda, AWS Step Functions, et Amazon API Gateway. Dans chacun de ces cas, il est possible de suivre une requête depuis le producteur jusqu’au consommateur de l’évènement.

Le dépôt GitHub contient des exemples démontrant l’utilisation du suivi actif avec les cibles EventBridge. L’application webhook prend en charge un paramètre de requête nommé target pour déterminer quels évènements sont acheminés vers ces cibles.

Afin que X-Ray détecte chaque service indiqué dans le webhook, le suivi doit être activé à la fois sur API Gateway et la fonction Lambda. Dans le template AWS SAM, la propriété Tracing: Active active le suivi pour la fonction Lambda. Si aucun rôle IAM n’est spécifié, le CLI AWS SAM ajoute automatiquement la stratégie arn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess au rôle d’exécution de la fonction Lambda. En ce qui concerne la définition de l’API, le suivi est activé en ajoutant TracingEnabled: True pour cette étape (stage) de l’API.

A l’invocation du webhook du point d’accès de l’API, X-Ray crée une carte de suivi correspondant à la requête, présentant chaque service depuis l’appel API REST jusqu’à l’envoi de l’évènement au bus :

X-Ray trace

Les logs Amazon CloudWatch de la fonction Lambda du webhook affichent l’évènement qui été placé sur le bus :

CloudWatch logs

Trace avec une fonction Lambda cible

Dans l’application exemple targets-lambda, la fonction Lambda utilise le SDK X-Ray et le suivi est activé dans le template AWS SAM :

Resources:
    ConsumerFunction:
        Type: AWS::Serverless::Function
        Properties:
            CodeUri: src/
            Handler: app.handler
            MemorySize: 128
            Timeout: 3
            Runtime: nodejs16.x
            Tracing: Active

Avec ces modifications, la fonction Lambda ciblée propage l’en-tête de suivi à partir de la requête webhook d’origine. Lorsque l’API webhook est invoquée, la carte de suivi X-Ray montre la requête complète jusqu’à la fonction Lambda cible. X-Ray affiche deux noeuds pour Lambda – le premier concerne le service Lambda et le second l’invocation de la fonction :

X-Ray trace

Trace avec API Gateway pour cible

Actuellement, le suivi actif n’est disponible que pour les APIs REST, pas pour les APIs HTTP. Vous pouvez activer le suivi X-Ray à l’aide du CLI AWS ou dans le menu Stages de la console API Gateway console, sous l’onglet Logs/Tracing :

X-Ray API Gateway

Avec AWS SAM, il n’est pas possible de créer une API Gateway pour EventBridge. Pour invoquer un point d’accès API depuis la console EventBridge, créez une règle et sélectionnez “API” en tant que cible. La création des permissions nécessaires à EventBridge pour invoquer le point d’accès est automatique.

EventBridge target

Si l’API elle-même invoque des services en aval pour lesquels le suivi actif est disponible, ces services apparaitront aussi comme des noeuds dans la carte des services X-Ray. Une fois l’application webhook utilisée pour invoquer l’API Gateway cible, la trace affiche la requête complète depuis l’appel API initial jusqu’à la seconde API cible :

X-Ray trace

Trace avec une cible Step Functions

L’activation du suivi pour une cible Step Functions se fait au sein de la définition de la machine d’état, et nécessite de lui donner les permissions en écriture sur X-Ray. Le template AWS SAM permet d’activer le suivi, de définir la règle EventBridge et d’utiliser la stratégie IAM AWSXRayDaemonWriteAccess dans une seule ressource :

WorkFlowStepFunctions:
  Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionUri: definition.asl.json
      DefinitionSubstitutions:
        LoggerFunctionArn: !GetAtt LoggerFunction.Arn
      Tracing:
        Enabled: True
      Events:
        UploadComplete:
          Type: EventBridgeRule
          Properties:
            Pattern:
              account:- !Sub '${AWS::AccountId}'
              source:- !Ref EventSource
              detail:
                apiEvent:
                  target:- 'sfn'
    
    Policies:
      - AWSXRayDaemonWriteAccess
      - LambdaInvokePolicy:
          FunctionName: !Ref LoggerFunction

Si la machine d’état utilise des services qui proposent le suivi actif, ceux-ci apparaitront aussi dans la carte de suivi et les traces pour les requêtes individuelles. Une fois cette cible invoquée avec le webhook, X-Ray affiche maintenant le suivi jusqu’à la machine d’état et les fonctions Lambda qu’elle comporte.

X-Ray trace Step Function

Ajout du suivi X-Ray à des cibles Lambda existantes

Pour encapsuler le SDK client AWS, il faut activer le suivi actif et inclure le SDK AWS X-Ray dans le package déployé pour la fonction Lambda. Contrairement au SDK AWS, le SDK X-Ray n’est pas inclus dans l’environnement d’exécution Lambda.

Une autre possibilité consiste à inclure le SDK X-Ray sous la forme d’une layer (“couche“) Lambda. Vous pouvez construire cette couche en suivant les instructions du dépôt GitHub. Une fois déployée, vous pouvez attacher le layer X-Ray à n’importe quelle fonction Lambda à l’aide de le console ou du CLI :

X-Ray Lambda

Pour en savoir plus sur les layers (“couches”) Lambda, vous pouvez vous référer à l’article (en anglais) Using Lambda layers to simplify your development process.

Conclusion

X-Ray est un outil efficace pour l’observabilité des applications serverless. Avec l’ajout de la propagation du contexte de suivi X-Ray pour EventBridge, le suivi de requêtes au sein d’applications distribuées est encore simplifié. Cet article a présenté un exemple applicatif avec trois types de cibles qui supportent le suivi actif par X-Ray. Pour chacun des cas, il explique comment activer ce suivi, en utilisant la console AWS ou AWS SAM, et montre la carte de suivi X-Ray résultante. Pour en apprendre plus sur le suivi actif avec des évènements, vous pouvez lire le Guide du développeur X-Ray ou la documentation Amazon EventBridge.

Pour plus de ressources concernant le serverless, visitez Serverless Land.

Article original écrit par James Beswick, Principal Developer Advocate pour l’équipe AWS Serverless Team et adapté en français par Olivier Chappe, Solutions Architect dans les équipes Game Tech.