AWS X-Ray et Step Functions

Vous pouvez l'utiliser AWS X-Raypour visualiser les composants de votre machine d'état, identifier les goulots d'étranglement liés aux performances et résoudre les demandes qui ont entraîné une erreur. Votre machine d'état envoie des données de suivi à X-Ray, et X-Ray traite les données pour générer une carte des services et des résumés de suivi consultables.

Lorsque X-Ray est activé pour votre machine d'état, vous pouvez suivre les demandes telles qu'elles sont exécutées dans Step Functions, dans toutes les AWS régions où X-Ray est disponible. Cela vous donne un aperçu détaillé de l'ensemble d'une demande Step Functions. Step Functions enverra des traces à X-Ray pour les exécuter par State Machine, même si aucun identifiant de trace n'est transmis par un service en amont. Vous pouvez utiliser une carte des services X-Ray pour visualiser la latence d'une demande, y compris les AWS services intégrés à X-Ray. Vous pouvez également configurer des règles d'échantillonnage pour indiquer à X-Ray quelles demandes enregistrer et à quelles fréquences d'échantillonnage, selon les critères que vous spécifiez.

Lorsque X-Ray n'est pas activé pour votre machine à états et qu'un service en amont ne transmet pas d'identifiant de trace, Step Functions n'envoie pas de traces à X-Ray pour les exécutions par machine à états. Toutefois, si un identifiant de trace est transmis par un service en amont, Step Functions enverra ensuite des traces à X-Ray pour les exécuter par des machines à états.

Vous pouvez l'utiliser AWS X-Ray avec Step Functions dans les régions où les deux sont compatibles. Consultez les pages relatives aux points de terminaison et aux quotas de Step Functions et de X-Ray pour plus d'informations sur le support régional pour X-Ray et Step Functions.

Quotas combinés pour X-Ray et Step Functions

Vous pouvez ajouter des données à une trace pendant sept jours au maximum et interroger les données de trace remontant à trente jours, soit la durée pendant laquelle X-Ray stocke les données de trace. Vos traces seront soumises à des quotas X-Ray. Outre les autres quotas, X-Ray fournit une taille de trace minimale garantie de 100 Ko pour les machines à états Step Functions. Si plus de 100 Ko de données de suivi sont fournies à X-Ray, cela peut entraîner le gel du tracé. Consultez la section Quotas de service de la page Points de terminaison et quotas de X-Ray pour plus d'informations sur les autres quotas pour X-Ray.

Important

Step Functions ne prend pas en charge le suivi X-Ray pour les exécutions de flux de travail secondaires lancées par un état de carte distribuée, car il est facile de dépasser la limite de taille du document Trace pour de telles exécutions.

Installation et configuration

Activer le traçage X-Ray lors de la création d'une machine à états

Vous pouvez activer le suivi X-Ray lors de la création d'une nouvelle machine à états en sélectionnant Activer le traçage X-Ray sur la page Spécifier les détails.

1. Ouvrez la console Step Functions et choisissez Create state machine.

2. Sur la page Choisir une méthode de création, choisissez une option appropriée pour créer votre machine à états. Si vous choisissez Run a sample project, vous ne pouvez pas activer le suivi X-Ray lors de la création de la machine d'état, et vous devrez activer le suivi X-Ray une fois que votre machine d'état aura été créée. Pour plus d'informations sur l'activation de X-Ray dans une machine à états existante, consultezActiver X-Ray dans une machine à états existante.

   Choisissez Suivant.

3. Sur la page Spécifier les détails, configurez votre machine d'état.

4. Choisissez Enable X-Ray Tracing.

   

   Votre machine à états Step Functions va désormais envoyer des traces à X-Ray pour les exécutions par machine à états.

   Note

   Si vous choisissez d'utiliser un rôle IAM existant, vous devez vous assurer que les écritures X-Ray sont autorisées. Pour plus d'informations sur les autorisations dont vous avez besoin, consultez les politiques IAM pour X-Ray.

Activer X-Ray dans une machine à états existante

Pour activer X-Ray sur une machine à états existante, procédez comme suit :

1. Dans la console Step Functions, sélectionnez la machine à états pour laquelle vous souhaitez activer le suivi.

2. Choisissez Modifier.

3. Choisissez Enable X-Ray Tracing.

   

   Vous verrez une notification vous indiquant que vous devrez peut-être apporter des modifications supplémentaires.

   Note

   Lorsque vous activez X-Ray pour une machine à états existante, vous devez vous assurer que vous disposez d'une politique IAM qui accorde des autorisations suffisantes pour permettre à X-Ray d'effectuer des traces. Vous pouvez soit en ajouter un manuellement, soit en générer un. Pour plus d'informations, consultez la section relative à la politique IAM pourPolitiques IAM pour AWS X-Ray.

4. (Facultatif) Générez automatiquement un nouveau rôle pour votre machine d'État afin d'inclure les autorisations X-Ray.

5. Choisissez Enregistrer.

Configurer le traçage X-Ray pour Step Functions

Lorsque vous exécutez pour la première fois une machine à états avec le suivi X-Ray activé, elle utilise les valeurs de configuration par défaut pour le suivi X-Ray. AWS X-Ray ne collecte pas de données pour chaque demande envoyée à une application. Il collecte plutôt des données pour un nombre de demandes statistiquement significatif. Par défaut, la première demande est enregistrée chaque seconde, et cinq pour cent des demandes supplémentaires. Une demande par seconde est le réservoir. Ceci garantit qu'au moins une trace est enregistrée chaque seconde aussi longtemps que le service traite les demandes. 5 % est la fréquence à laquelle les demandes supplémentaires au-delà du réservoir sont échantillonnées.

Afin de ne pas encourir de frais de service lors de la mise en route, le taux d'échantillonnage par défaut est prudent. Vous pouvez configurer X-Ray pour modifier la règle d'échantillonnage par défaut et configurer des règles supplémentaires qui appliquent l'échantillonnage en fonction des propriétés du service ou de la demande.

Par exemple, vous souhaiterez peut-être désactiver l'échantillonnage et suivre toutes les demandes d'appels qui modifient l'état, le descripteur Comptes AWS ou les transactions. Pour les appels en lecture seule à volume élevé, tels que les sondages d'antécédents, les vérifications de santé ou la maintenance de la connexion, vous pouvez effectuer un échantillonnage à faible débit tout en obtenant suffisamment de données pour détecter les problèmes qui se produisent.

Pour configurer une règle d'échantillonnage pour votre machine à états :

1. Accédez à la console X-Ray.

2. Choisissez Sampling (Échantillonnage).

3. Pour créer une règle, choisissez Create sampling rule (Créer une règle d’échantillonnage).

   Pour modifier une règle, choisissez le nom d'une règle.

   Pour supprimer une règle, choisissez une règle et utilisez le menu Actions pour la supprimer.

Certaines parties des règles d'échantillonnage existantes, telles que le nom et la priorité, ne peuvent pas être modifiées. Ajoutez ou clonez plutôt une règle existante, apportez les modifications souhaitées, puis utilisez la nouvelle règle.

Pour des informations détaillées sur les règles d'échantillonnage X-Ray et sur la façon de configurer les différents paramètres, voir Configuration des règles d'échantillonnage dans la console X-Ray.

Intégrez les services en amont

Pour intégrer l'exécution des flux de travail Step Functions, tels que les flux de travail Express, Synchrone et Standard, à un service en amont, vous devez définir letraceHeader. Cela se fait automatiquement pour vous si vous utilisez une API HTTP dans API Gateway. Toutefois, si vous utilisez une fonction Lambda et/ou un SDK, vous devez définir vous-même les appels d'StartSyncExecutionAPI traceHeader on the StartExecutionor.

Vous devez spécifier le traceHeader format sous la forme\p{ASCII}∗. En outre, pour permettre à Step Functions d'utiliser le même identifiant de trace, vous devez spécifier le format sous la formeRoot={TRACE_ID};Sampled={1 or 0}. Si vous utilisez une fonction Lambda, remplacez le par l'ID TRACE_ID de trace dans votre segment actuel et définissez le champ Sampled comme 1 si votre mode d'échantillonnage était vrai et 0 si votre mode d'échantillonnage était faux. La fourniture de l'ID de trace dans ce format garantit que vous obtiendrez une trace complète.

Voici un exemple écrit en Python pour montrer comment spécifier letraceHeader.

state_machine = config.get_string_paramter("STATE_MACHINE_ARN")
    if (xray_recorder.current_subsegment() is not None and 
        xray_recorder.current_subsegment().sampled) :
        trace_id = "Root={};Sampled=1".format(
            xray_recorder.current_subsegment().trace_id
        )
    else:
        trace_id = "Root=not enabled;Sampled=0"
    LOGGER.info("trace %s", trace_id)
    
    # execute it
    response = states.start_sync_execution(
        stateMachineArn=state_machine,
        input=event['body'],
        name=context.aws_request_id,
        traceHeader=trace_id
    )
    LOGGER.info(response)

Concepts

La console X-Ray

La AWS X-Ray console vous permet de visualiser les cartes de service et les traces des demandes traitées par vos applications. Vous pouvez accéder à la console pour consulter les informations détaillées collectées par X-Ray lorsqu'il est activé pour votre machine à états.

Consultez Affichage de la console X-Ray pour savoir comment accéder à la console X-Ray pour les exécutions de vos machines à états.

Pour des informations détaillées sur la console X-Ray, consultez la documentation de la console X-Ray.

Segments, sous-segments et traces

Un segment enregistre les informations relatives à une demande adressée à votre machine d'état. Il contient des informations telles que le travail effectué par votre machine d'état, et peut également contenir des sous-segments contenant des informations sur les appels en aval.

Une trace rassemble tous les segments générés par une seule demande.

Echantillonnage

Pour garantir un suivi efficace et fournir un échantillon représentatif des demandes traitées par votre application, X-Ray applique un algorithme d'échantillonnage afin de déterminer quelles demandes sont suivies. Cela peut être modifié en modifiant les règles d'échantillonnage.

Métriques

Pour votre machine à états, X-Ray mesurera le temps d'invocation, le temps de transition entre états, le temps d'exécution global de Step Functions et les variations de ce temps d'exécution. Ces informations sont accessibles via la console X-Ray.

Analyse

La console AWS X-Ray Analytics est un outil interactif permettant d'interpréter les données de suivi. Vous pouvez affiner l’ensemble de données actif en appliquant des filtres de plus en plus précis. Pour ce faire, cliquez sur les graphiques, les panneaux de métriques et les champs associés à l’ensemble de suivis sélectionné. Cela vous permet d'analyser les performances de votre machine à états, de localiser et d'identifier rapidement les problèmes de performances.

Pour des informations détaillées sur les analyses X-Ray, voir Interaction avec la console AWS X-Ray Analytics

Intégrations des services Step Functions et X-Ray

Certains des AWS services intégrés à Step Functions fournissent une intégration AWS X-Ray en ajoutant un en-tête de suivi aux demandes, en exécutant le daemon X-Ray ou en prenant des décisions d'échantillonnage et en téléchargeant les données de suivi vers X-Ray. Les autres doivent être instrumentés à l'aide du AWS X-Ray SDK. Quelques-uns ne prennent pas encore en charge l'intégration de X-Ray. L'intégration de X-Ray est nécessaire pour fournir des données de suivi complètes lors de l'utilisation d'une intégration de service avec Step Functions

Support pour Native X-Ray

Les intégrations de services avec le support natif de X-Ray incluent :

• Amazon Simple Notification Service

• Amazon Simple Queue Service

• AWS Lambda

• AWS Step Functions

Instrumentation requise

Intégrations de services nécessitant une instrumentation X-Ray :

• Amazon Elastic Container Service

• AWS Batch

• AWS Fargate

Trace côté client uniquement

Les autres intégrations de services ne prennent pas en charge les traces X-Ray. Cependant, les traces côté client peuvent toujours être collectées :

• Amazon DynamoDB

• Amazon EMR

• Amazon SageMaker

• AWS CodeBuild

• AWS Glue

Affichage de la console X-Ray

X-Ray reçoit les données des services sous forme de segments. X-Ray regroupe les segments ayant une requête commune dans des traces. X-Ray traite les traces pour générer un graphe de service fournissant une représentation visuelle de votre application.

Après avoir démarré l'exécution de votre machine à états, vous pouvez consulter ses traces X-Ray en cliquant sur le lien X-Ray Trace Map dans la section Détails de l'exécution.

Une fois que vous avez activé X-Ray pour votre machine d'état, vous pouvez consulter les informations de suivi de ses exécutions dans la console X-Ray.

Afficher les informations de traçage X-Ray pour Step Functions

Les étapes suivantes illustrent le type d'informations que vous pouvez voir dans la console après avoir activé X-Ray et exécuté une exécution. Les traces X-Ray de l'Exemple de modèle de rappel (Amazon SQS, Amazon SNS, Lambda) exemple de projet sont affichées.

Suivis

Une fois l'exécution terminée, vous pouvez accéder à la console X-Ray, où vous verrez la page X-Ray Traces. Cela affiche une vue d'ensemble de la carte des services ainsi que des informations de suivi et de segment pour votre machine à états.

Cartographie des services

La carte des services de la console X-Ray vous permet d'identifier les services présentant des erreurs, des connexions présentant une latence élevée, ou de consulter les traces des demandes infructueuses.

Sur la carte de suivi, vous pouvez choisir un nœud de service pour afficher les demandes relatives à ce nœud, ou une limite entre deux nœuds pour afficher les demandes ayant transité par cette connexion. Ici, le WaitForCallBack nœud a été sélectionné et vous pouvez consulter des informations supplémentaires sur son exécution et son état de réponse.

Vous pouvez voir comment la carte du service X-Ray est corrélée à la machine à états. Il existe un nœud de carte des services pour chaque intégration de services appelé par Step Functions, à condition qu'il soit compatible avec X-Ray.

Segments et sous-segments

Une trace est un ensemble de segments générés par une seule demande. Chaque segment fournit le nom de la ressource, des détails sur la demande et des détails sur le travail effectué. Sur la page Traces, vous pouvez voir les segments et, s'ils sont développés, les sous-segments correspondants. Vous pouvez choisir un segment ou un sous-segment pour afficher des informations détaillées le concernant.

Choisissez chacun des onglets pour voir comment les informations relatives aux segments et sous-segments sont affichées.

Overview of Segments

Vue d'ensemble des segments et sous-segments de cette machine à états. Il existe un segment différent pour chaque nœud sur la carte des services.

View segment detail

Le choix d'un segment fournit le nom de la ressource, des détails sur la demande et des détails sur le travail effectué.

View subsegment detail

Un segment peut décomposer les données concernant le travail effectué en sous-segments. Le choix d'un sous-segment vous permet d'afficher des informations et des détails de chronométrage plus précis. Un sous-segment peut contenir des informations supplémentaires sur un appel à un AWS service, à une API HTTP externe ou à une base de données SQL.

Analyse

La console AWS X-Ray Analytics est un outil interactif permettant d'interpréter les données de suivi. Vous pouvez l'utiliser pour comprendre plus facilement les performances de votre machine à états. La console vous permet d'explorer, d'analyser et de visualiser les suivis grâce à des graphiques interactifs sur les temps de réponse et la chronologie. Cela peut vous aider à identifier rapidement les problèmes de performances et de latence.

Vous pouvez affiner l’ensemble de données actif en appliquant des filtres de plus en plus précis. Pour ce faire, cliquez sur les graphiques, les panneaux de métriques et les champs associés à l’ensemble de suivis sélectionné.

Configuration

Vous pouvez configurer les options d'échantillonnage et de chiffrement depuis la console X-Ray.

Sampling

Choisissez Échantillonnage pour afficher les détails relatifs à la fréquence d'échantillonnage et à la configuration. Vous pouvez modifier les règles d'échantillonnage pour contrôler la quantité de données que vous enregistrez et modifier le comportement d'échantillonnage en fonction de vos besoins spécifiques.

Encryption

Choisissez Chiffrement pour modifier les paramètres de chiffrement. Vous pouvez utiliser le paramètre par défaut, dans lequel X-Ray chiffre les traces et les dates au repos, ou, si nécessaire, vous pouvez choisir une clé principale client. AWS KMSLes frais standard s'appliquent dans ce dernier cas.

Que se passe-t-il s'il n'y a aucune donnée dans la carte de suivi ou la carte des services ?

Si vous avez activé X-Ray, mais que vous ne voyez aucune donnée dans la console X-Ray, vérifiez que :

• Vos rôles IAM sont correctement configurés pour permettre l'écriture dans X-Ray.

• Les règles d'échantillonnage permettent l'échantillonnage des données.

• Comme il peut s'écouler un court délai avant que les rôles IAM nouvellement créés ou modifiés ne soient appliqués, vérifiez à nouveau le tracé ou les cartes des services après quelques minutes.

• Si Data Not Found apparaît dans le panneau X-Ray Traces, vérifiez les paramètres de votre compte IAM et assurez-vous qu'ils AWS Security Token Service sont activés pour la région souhaitée. Pour plus d'informations, consultez la section Activation et désactivation AWS STS dans et Région AWS dans le guide de l'utilisateur IAM.