Documents de segment AWS X-Ray - AWS X-Ray
Champs de segmentSous-segmentsDonnées de demande HTTPAnnotationsMetadonnéesAWSDonnées de ressourcesErreurs et exceptionsRequêtes SQL

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Documents de segment AWS X-Ray

Un segment de suivi est une représentation JSON d'une demande que sert votre application. Un segment de suivi enregistre les informations sur la demande originale, les informations sur le travail que votre application effectue en local etsous-segmentsavec les informations sur les appels en aval que votre application effectue versAWSressources, API HTTP et bases de données SQL.

UNDocument de segmenttransmet les informations sur un segment à pour pour pour pour X-Ray pour pour Un document de segment peut atteindre jusqu'à 64 kB et contenir un ensemble complet avec des sous-segments, un fragment de segment qui indique qu'une demande est en cours ou un seul sous-segment envoyé séparément. Vous pouvez envoyer les documents de segment directement à pour pour X-Ray pour pour pour pour pourPutTraceSegmentsAPI.

X-Ray compile et traite des documents segmentés pour générer des documents interrogeablesRésumés de suivisetsuivisauquel vous pouvez accéder en utilisant leGetTraceSummariesetBatchGetTracesAPI, respectivement. Outre les segments et sous-segments que vous envoyez à X-Ray, le service utilise les informations des sous-segments pour générerSegments inférenceet les ajoute à la suivis. Les segments déduits représentent les ressources et services en aval de la cartographie des services.

X-Rayschéma JSONpour les documents de segment. Vous pouvez télécharger le schéma ici : xray-segmentdocument-schema-v1.0.0. Les champs et les objets figurant dans le schéma sont décrits plus en détail dans les sections suivantes.

Un sous-ensemble de champs de segment est indexé par pour X-Ray utilisation avec les expressions de filtre. Par exemple, si vous définissez l'objetusersur un segment avec un identifiant unique, vous pouvez rechercher les segments associés aux utilisateurs spécifiques de la console X-Ray ou à l'aide de laGetTraceSummariesAPI. Pour plus d'informations, consultez Utilisation des expressions de filtre.

Lorsque vous instrumentez votre application avec le kit de développement X-Ray pour pour pour pour pour pour pour pour pour pour pour pour pour pour vous. Au lieu d'envoyer les documents de segment directement à pour pour pour pour pour pour pour pour pour pourDémon X-Ray. Pour plus d'informations, consultez Envoi de documents de segment au démon X-Ray.

Champs de segment

Un segment enregistre les informations de suivi d'une demande que votre application sert. Au minimum, un segment enregistre le nom, l'ID, l'heure de début, l'ID de suivi et l'heure de fin de la demande.

Exemple Segment terminé minimal
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Les champs suivants sont obligatoires, ou soumis à condition, pour les segments.

Note

Les valeurs doivent être des chaînes (jusqu'à 250 caractères), sauf mention contraire.

Champs de segment obligatoires

  • name— Nom logique du service qui a traité la demande, jusqu'à200 caractères. Par exemple, le nom de votre application ou le nom de domaine. Les noms peuvent contenir des lettres en Unicode, des nombres et des espaces, ainsi que les symboles suivants : _, ., :, /, %, &, #, =, +, \, -, @

  • id— Identificateur 64 bits pour le segment, unique parmi les segments du même suivi, dans16 chiffres hex.

  • trace_id— Identificateur unique qui connecte tous les segments et sous-segments provenant d'une demande client unique.

    Format d'ID de suivi

    Un trace_id consiste en trois nombres séparés par des tirets. Par exemple, 1-58406520-a006649127e371903a2de979. Cela comprend :

    • Le numéro de version est 1.

    • La durée de la demande originale, en heure d'époque Unix, sur 8 chiffres hexadécimaux.

      Par exemple, 10 h le 1er décembre 2016 PST en heure d'époque Unix correspond à 1480615200 secondes, ou 58406520 en chiffres hexadécimaux.

    • Un identificateur de 96 bits pour le suivi, globalement unique, de 24 chiffres hexadécimaux.

    Sécurité de l'ID de suivi

    Les ID de suivi sont visibles dans les en-têtes de réponse. Générez des ID de suivi avec un algorithme aléatoire sécurisé pour garantir que les attaquants ne puissent pas calculer vos futurs ID de suivi et envoyer des demandes à votre application avec ces ID.

  • start_time–nombreheure à laquelle le segment a été créé, en secondes codées en virgule flottante en heure UNIX. Par exemple, 1480615200.010 ou 1.480615200010E9. Utilisez autant de décimales que nécessaire. La résolution en microsecondes est recommandée si elle est disponible.

  • end_time–nombrec'est à cette époque que le segment a été fermé. Par exemple, 1480615200.090 ou 1.480615200090E9. Spécifiez une end_time ou in_progress.

  • in_progress–booléen, défini surtrueau lieu de spécifierend_timepour enregistrer qu'un segment a démarré, mais qu'il n'est pas terminé. Envoyez un segment en cours lorsque votre application reçoit une demande longue à servir, pour suivre la réception de la demande. Lorsque la réponse est envoyée, envoyez le segment terminé pour remplacer le segment en cours. N'envoyez qu'un segment complet, et un ou zéro segment en cours, par demande.

Service

Un segmentnamedoit correspondre au nom de domaine ou au nom logique du service qui génère le segment. Toutefois, cela n'est pas appliqué. Toute application qui est autorisée àPutTraceSegmentspeut envoyer des segments avec n'importe quel nom.

Les champs suivants sont facultatifs pour les segments.

Champs de segment facultatifs

  • service— Objet avec les informations relatives à votre application.

    • version— Chaîne qui identifie la version de votre application ayant servi la demande.

  • user— Chaîne qui identifie l'utilisateur ayant envoyé la demande.

  • origin— TypeAWSressource qui exécute votre application.

    Valeurs prises en charge

    • AWS::EC2::Instance— Une instance Amazon EC2.

    • AWS::ECS::Container— Un conteneur Amazon ECS.

    • AWS::ElasticBeanstalk::Environment— Environnement Elastic Beanstalk.

    Lorsque plusieurs valeurs sont applicables à votre application, utilisez celle qui est la plus spécifique. Par exemple, un environnement Docker Elastic Beanstalk multi-conteneurs exécute votre application sur un conteneur Amazon ECS, qui s'exécute à son tour sur une instance Amazon EC2. Dans ce cas, vous devez définir l'origine sur AWS::ElasticBeanstalk::Environment car l'environnement est le parent des deux autres ressources.

  • parent_id— ID de sous-segment que vous spécifiez si la demande provient d'une application instrumentée. Le kit X-Ray SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDKen-tête de suivipour les appels HTTP en aval. Dans le cas de sous-segments imbriqués, un sous-segment peut avoir un segment ou un sous-segment comme parent.

  • http–httpObjets avec les informations sur la demande HTTP d'origine.

  • aws–awsObjet avec les informations sur l'objetAWSressource sur laquelle votre application a servi la demande.

  • error,throttle,fault, etcause–erreurChamps qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception ayant provoqué l'erreur.

  • annotations–annotationsObjet avec les paires clé-valeur que X-Ray pour la recherche.

  • metadata–metadataObjet avec les données supplémentaires que vous voulez stocker dans le segment.

  • subsegments–gammedesubsegmentobjets.

Sous-segments

Vous pouvez créer des sous-segments pour enregistrer les appels versAWSles services et les ressources que vous créez avecAWSKit SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK Vous pouvez également créer des sous-segments pour déboguer ou annoter les blocs de code de votre application. Comme les sous-segments peuvent contenir d'autres sous-segments, un sous-segment personnalisé qui enregistre les métadonnées relatives à un appel de fonction interne peut contenir d'autres sous-segments personnalisés et les sous-segments d'appels en aval.

Un sous-segment enregistre un appel en aval du point de vue du service qui l'appelle. X-Ray utilise des sous-segments pour identifier des services en aval qui n'envoient pas de segments et créent des entrées pour eux sur le graphique de services.

Un sous-segment peut être intégré dans un document de segment entier, ou envoyé séparément. Envoyez des sous-segments séparément aux appels en aval de suivi de manière asynchrone pour les demandes de longue durée, ou pour éviter de dépasser la taille du document de segment maximum.

Exemple Segment avec sous-segment intégré

Un sous-segment indépendant possède type comme subsegment et un parent_id qui identifie le segment parent.

{
  "trace_id"   : "1-5759e988-bd862e3fe1be46a994272793",
  "id"         : "defdfd9912dc5a56",
  "start_time" : 1461096053.37518,
  "end_time"   : 1461096053.4042,
  "name"       : "www.example.com",
  "http"       : {
    "request"  : {
      "url"        : "https://www.example.com/health",
      "method"     : "GET",
      "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
      "client_ip"  : "11.0.3.111"
    },
    "response" : {
      "status"         : 200,
      "content_length" : 86
    }
  },
  "subsegments" : [
    {
      "id"         : "53995c3f42cd8ad8",
      "name"       : "api.example.com",
      "start_time" : 1461096053.37769,
      "end_time"   : 1461096053.40379,
      "namespace"  : "remote",
      "http"       : {
        "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
        },
        "response" : {
          "status"         : 200,
          "content_length" : 861
        }
      }
    }
  ]
}

Pour les demandes de longue durée, vous pouvez envoyer un segment de progression afin d'avertir X-Ray que la demande a été reçue, puis envoyer séparément les sous-segments pour les suivre avant de terminer la demande originale.

Exemple Segment en cours
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}
Exemple Sous-segment indépendant

Un sous-segment indépendant possède type comme subsegment, un trace_id et un parent_id qui identifie le segment parent.

{
  "name" : "api.example.com",
  "id" : "53995c3f42cd8ad8",
  "start_time" : 1.478293361271E9,
  "end_time" : 1.478293361449E9,
  "type" : "subsegment",
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  "parent_id" : "defdfd9912dc5a56",
  "namespace"  : "remote",
  "http"       : {
      "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
      },
      "response" : {
          "status"         : 200,
          "content_length" : 861
      }
  }
}

Lorsque la demande est terminée, fermez le segment en le renvoyant avec un end_time. Le segment complet remplace le segment en cours.

Vous pouvez également envoyer des sous-segments séparément pour les demandes complètes qui ont déclenché des workflows asynchrones. Par exemple, une API Web peut renvoyer une réponse OK 200 juste avant de démarrer le travail que l'utilisateur demandé. Vous pouvez envoyer un segment complet à X-Ray dès que la réponse a été envoyée, suivi des sous-segments pour compléter le travail ultérieurement. Comme pour les segments, vous pouvez aussi envoyer un fragment de sous-segment pour enregistrer le démarrage du sous-segment, puis le remplacer par un sous-segment complet une fois que l'appel en aval est terminé.

Les champs suivants sont obligatoires, ou soumis à condition, pour les sous-segments.

Note

Les valeurs doivent être des chaînes (jusqu'à 250 caractères), sauf mention contraire.

Champs de sous-segment obligatoires

  • id— Identificateur 64 bits pour le sous-segment, unique parmi les segments du même suivi, dans16 chiffres hex.

  • name— Nom logique du sous-segment. Pour les appels en aval, nommez le sous-segment après l'appel de la ressource ou du service. Pour les sous-segments personnalisés, nommez le sous-segment après le code qu'il instrumente (par exemple, un nom de fonction).

  • start_time–nombreheure à laquelle le sous-segment a été créé, en secondes codées en virgule flottante, en heure Unix, qui offre une précision à la milliseconde. Par exemple, 1480615200.010 ou 1.480615200010E9.

  • end_time–nombrec'est à ce moment que le sous-segment a été fermé. Par exemple, 1480615200.090 ou 1.480615200090E9. Spécifiez une end_time ou in_progress.

  • in_progress–booléenqui est défini surtrueau lieu de spécifierend_timepour enregistrer qu'un sous-segment a démarré, mais qu'il n'est pas terminé. Envoyez uniquement un sous-segment complet, et un ou zéro sous-segment en cours, par demande en aval.

  • trace_id— ID de suivi du segment parent du sous-segment. Obligatoire uniquement en cas d'envoi séparé d'un sous-segment.

    Format d'ID de suivi

    Un trace_id consiste en trois nombres séparés par des tirets. Par exemple, 1-58406520-a006649127e371903a2de979. Cela comprend :

    • Le numéro de version est 1.

    • La durée de la demande originale, en heure d'époque Unix, sur 8 chiffres hexadécimaux.

      Par exemple, 10 h le 1er décembre 2016 PST en heure d'époque Unix correspond à 1480615200 secondes, ou 58406520 en chiffres hexadécimaux.

    • Un identificateur de 96 bits pour le suivi, globalement unique, de 24 chiffres hexadécimaux.

  • parent_id: ID de segment du segment parent du sous-segment. Obligatoire uniquement en cas d'envoi séparé d'un sous-segment. Dans le cas de sous-segments imbriqués, un sous-segment peut avoir un segment ou un sous-segment comme parent.

  • type–subsegment. Obligatoire uniquement en cas d'envoi séparé d'un sous-segment.

Les champs suivants sont facultatifs pour les sous-segments.

Champs de sous-segment facultatifs

  • namespace–awspour les appels du SDK AWS ;remotepour les autres appels en aval.

  • http–httpObjet avec les informations sur un appel HTTP sortant.

  • aws–awsObjet avec les informations sur l'objetAWSressource que votre application a appelée.

  • error,throttle,fault, etcause–erreurChamps qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception ayant provoqué l'erreur.

  • annotations–annotationsObjet avec les paires clé-valeur que X-Ray pour la recherche.

  • metadata–metadataObjet avec les données supplémentaires que vous voulez stocker dans le segment.

  • subsegments–gammedesubsegmentobjets.

  • precursor_ids–gammed'ID de sous-segment qui identifie les sous-segments ayant le même parent que celui qui s'est terminé avant ce sous-segment.

Données de demande HTTP

Utilisez un bloc HTTP pour enregistrer les détails relatifs à une demande HTTP que votre application a servie (dans un segment) ou que votre application a effectuée auprès d'une API HTTP en aval (dans un sous-segment). La plupart des champs de cet objet correspondent aux informations disponibles dans une demande et une réponse HTTP.

http

Tous les champs sont facultatifs.

  • request— Informations sur une demande.

    • method— Méthode de la demande. Par exemple, GET.

    • url— URL complète de la demande, compilée à partir du protocole, du nom d'hôte et du chemin de la demande.

    • user_agent— Chaîne de l'agent utilisateur du demandeur.

    • client_ip— Adresse IP du demandeur. Peut être récupérée depuis la Source Address du paquet IP ou, pour les demandes acheminées, à partir d'un en-tête X-Forwarded-For.

    • x_forwarded_for— (segments uniquement)booléenindiquant que leclient_ipa été lu depuis unX-Forwarded-Foret n'est pas fiable, car il a pu être falsifié.

    • traced— (sous-segments uniquement)booléenindiquant que l'appel en aval concerne un autre service suivi. Si ce champ est défini surtrue, pour pour pour pour pour pour pour pour pour pour pour pour pour le service en aval charge un segment avec unparent_idqui correspond àiddu sous-segment qui contient ce bloc.

  • response— Informations sur une réponse.

    • status–entierindiquant l'état HTTP de la réponse.

    • content_length–entierindiquant la longueur du corps de la réponse en octets.

Lorsque vous instrumentez un appel vers une API web en aval, enregistrez un sous-segment avec les informations sur la demande et la réponse HTTP. Pour générer un segment déduit pour l'API à distance.

Exemple Segmentation pour un appel HTTP servi par une application s'exécutant sur Amazon EC2
{
  "id": "6b55dcc497934f1a",
  "start_time": 1484789387.126,
  "end_time": 1484789387.535,
  "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }
Exemple Sous-segment pour un appel HTTP en aval
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
Exemple Segment déduit pour un appel HTTP en aval
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

Annotations

Les segments et sous-segments peuvent inclure unannotationsObjet contenant un ou plusieurs champs que X-Ray pour une utilisation avec les expressions de filtre. Les champs peuvent avoir des valeurs de type chaîne, numérique ou booléen (ni objet ni tableau). X-Ray un maximum de 50 annotations par suivi.

Exemple Segment pour appel HTTP avec annotations
{
  "id": "6b55dcc497932f1a",
  "start_time": 1484789187.126,
  "end_time": 1484789187.535,
  "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "annotations": {
    "customer_category" : 124,
    "zip_code" : 98101,
    "country" : "United States",
    "internal" : false
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }

Les clés doivent être au format alphanumérique pour fonctionner avec les filtres. Les traits de soulignement sont autorisés. Les autres symboles et les espaces ne sont pas autorisés.

Metadonnées

Les segments et sous-segments peuvent inclure unmetadataObjet contenant un ou plusieurs champs avec des valeurs de n'importe quel type (types objet et tableau inclus). X-Ray n'indexe pas les métadonnées et les valeurs peuvent être de n'importe quelle taille, aussi longtemps que le document de segment ne dépasse pas la taille maximale (64 kB). Vous pouvez consulter les métadonnées dans le document de segment complet retourné par l'API BatchGetTraces. Clés de champ (debugdans l'exemple suivant) commençant parAWS.sont réservés à une utilisation parAWS-les kits SDK et les clients fournis.

Exemple Sous-segment personnalisé avec métadonnées
{
  "id": "0e58d2918e9038e8",
  "start_time": 1484789387.502,
  "end_time": 1484789387.534,
  "name": "## UserModel.saveUser",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
  "subsegments": [
    {
      "id": "0f910026178b71eb",
      "start_time": 1484789387.502,
      "end_time": 1484789387.534,
      "name": "DynamoDB",
      "namespace": "aws",
      "http": {
        "response": {
          "content_length": 58,
          "status": 200
        }
      },
      "aws": {
        "table_name": "scorekeep-user",
        "operation": "UpdateItem",
        "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
        "resource_names": [
          "scorekeep-user"
        ]
      }
    }
  ]
}

AWSDonnées de ressources

Pour les segments, l'objet aws contient les informations relatives à la ressource sur laquelle votre application est en cours d'exécution. Plusieurs champs peuvent s'appliquer à une même ressource. Par exemple, une application exécutée dans un environnement Docker à plusieurs conteneurs sur Elastic Beanstalk peut avoir des informations sur l'instance Amazon EC2, le conteneur Amazon ECS s'exécutant sur l'instance et l'environnement Elastic Beanstalk lui-même.

aws (Segments)

Tous les champs sont facultatifs.

  • account_id— Si votre application envoie des segments à un autreAWS, enregistrez l'ID du compte en cours d'exécution sur votre application.

  • cloudwatch_logs— Tableau d'objets qui décrivent un CloudWatch groupe de journaux.

    • log_group— Le CloudWatch Nom du groupe de journaux.

    • arn— Le CloudWatch ARN de groupe de journaux.

  • ec2— Informations sur une instance Amazon EC2.

    • instance_id— ID d'instance de l'instance EC2.

    • instance_size— Type d'instance EC2.

    • ami_id— ID de l'Amazon Machine Image.

    • availability_zone— Zone de disponibilité dans laquelle l'instance est en cours d'exécution.

  • ecs— Informations sur un conteneur Amazon ECS.

    • container— Le nom d'hôte de votre conteneur.

    • container_id— L'identifiant complet de votre conteneur.

    • container_arn— Nom ARN de votre instance de conteneur.

  • eks— Informations sur un cluster Amazon EKS.

    • pod— Le nom d'hôte de votre module EKS.

    • cluster_name— Le nom du cluster EKS.

    • container_id— L'identifiant complet de votre conteneur.

  • elastic_beanstalk— Informations sur un environnement Elastic Beanstalk. Vous pouvez trouver ces informations dans un fichier nommé/var/elasticbeanstalk/xray/environment.confsur les dernières plateformes Elastic Beanstalk.

    • environment_name : Nom de l'environnement.

    • version_label— Nom de la version de l'application actuellement déployée sur l'instance ayant servi la demande.

    • deployment_id–nombreindiquant l'ID du dernier déploiement réussi sur l'instance ayant servi la demande.

  • xray— Métadonnées concernant le type et la version de l'instrumentation utilisée.

    • auto_instrumentation— Booléen indiquant si l'auto-instrumentation a été utilisée (par exemple, l'agent Java).

    • sdk_version— La version du SDK ou de l'agent utilisé.

    • sdk— Type de SDK.

Exemple AWSBloc avec plug-ins
"aws":{
   "elastic_beanstalk":{
      "version_label":"app-5a56-170119_190650-stage-170119_190650",
      "deployment_id":32,
      "environment_name":"scorekeep"
   },
   "ec2":{
      "availability_zone":"us-west-2c",
      "instance_id":"i-075ad396f12bc325a",
      "ami_id":
   },
   "cloudwatch_logs":[
      {
         "log_group":"my-cw-log-group",
         "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
      }
   ],
   "xray":{
      "auto_instrumentation":false,
      "sdk":"X-Ray for Java",
      "sdk_version":"2.8.0"
   }
}

Pour les sous-segments, enregistrez les informations surAWSservices et ressources auxquels votre application accède. X-Ray utilise ces informations pour créer des segments déduits qui représentent les services en aval de votre cartographie des services.

aws (Sous-segments)

Tous les champs sont facultatifs.

  • operation— Nom de l'action d'API appelée sur unAWSservice ou ressource.

  • account_id— Si votre application accède aux ressources d'un autre compte ou envoie les segments à un autre compte, enregistrez l'ID du compte détenteur deAWSressource à laquelle votre application a accédé.

  • region— Si la ressource est dans une région différente de votre application, enregistrez la région. Par exemple, us-west-2.

  • request_id— Identifiant unique de la demande.

  • queue_url— Pour les opérations sur une file d'attente Amazon SQS, l'URL de la file d'attente.

  • table_name— Pour les opérations sur une table DynamoDB, le nom de la table.

Exemple Sous-segment pour un appel vers DynamoDB pour enregistrer un objet
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

Erreurs et exceptions

Lorsqu'une erreur se produit, vous pouvez enregistrer les détails de l'erreur et les exceptions qui ont été générées. Enregistrez les erreurs dans les segments lorsque votre application renvoie une erreur à l'utilisateur et dans les sous-segments lorsqu'un appel en aval renvoie une erreur.

types d'erreur

Définissez un ou plusieurs des champs suivants sur true pour indiquer qu'une erreur s'est produite. Plusieurs types peuvent s'appliquer en cas d'erreurs composites. Par exemple, une erreur 429 Too Many Requests d'un appel en aval peut contraindre votre application à renvoyer 500 Internal Server Error, auquel cas les trois types s'appliquent.

  • error–booléenindiquant qu'une erreur client s'est produite (le code de statut de la réponse était 4XX Client Error).

  • throttle–booléenindiquant qu'une demande a été limitée (le code de statut de la réponse était429, nombre de demandes trop élevé).

  • fault–booléenindiquant qu'une erreur serveur s'est produite (le code de statut de la réponse était 5XX Server Error).

Indiquez la cause de l'erreur en incluant un objet cause dans le segment ou le sous-segment.

cause

Une cause peut être un ID d'exception sur 16 caractères ou un objet avec les champs suivants :

  • working_directory— Chemin complet du répertoire de travail lorsque l'exception s'est produite.

  • paths— Legammedes chemins vers les bibliothèques ou les modules en cours d'utilisation lorsque l'exception s'est produite.

  • exceptions— Legammedeexceptionobjets.

Incluez les informations détaillées sur l'erreur dans un ou plusieurs objets exception.

exception

Tous les champs sont facultatifs sauf id.

  • id— Identificateur 64 bits pour l'exception, unique parmi les segments du même suivi, dans16 chiffres hex.

  • message— Message de l'exception.

  • type— Type de l'exception.

  • remote–booléenindiquant que l'exception a été provoquée par une erreur renvoyée par un service en aval.

  • truncated–entierindiquant le nombre de frames de pile omis dans lastack.

  • skipped–entierindiquant le nombre d'exceptions ignorées entre cette exception et son enfant, autrement dit, l'exception qui a été provoquée.

  • cause— ID de l'exception parent de l'exception, autrement dit, l'exception ayant provoqué cette exception.

  • stack–gammedestackFrameobjets.

Le cas échéant, enregistrez les informations relatives à la pile des appels dans les objets stackFrame.

stackFrame

Tous les champs sont facultatifs.

  • path— Chemin d'accès relatif au fichier.

  • line— Ligne dans le fichier.

  • label— Nom de la fonction ou de la méthode.

Requêtes SQL

Vous pouvez créer des sous-segments pour les requêtes que votre application effectue auprès d'une base de données SQL.

sql

Tous les champs sont facultatifs.

  • connection_string— Pour SQL Server ou autres connexions de base de données qui n'utilisent pas les chaînes de connexion URL, enregistrez la chaîne de connexion, à l'exception des mots de passe.

  • url— Pour une connexion de base de données qui utilise une chaîne de connexion URL, enregistrez l'URL, à l'exception des mots de passe.

  • sanitized_query— Requête de base de données, avec n'importe quelles valeurs fournies par l'utilisateur supprimées ou remplacées par un espace réservé.

  • database_type— Nom du moteur de base de données.

  • database_version— Numéro de version du moteur de base de données.

  • driver_version— Nom et numéro de version du pilote du moteur de base de données que votre application utilise.

  • user— Nom de la base de données.

  • preparation–callsi la requête utilisait unPreparedCall;statementsi la requête utilisait unPreparedStatement.

Exemple Sous-segment avec une requête SQL
{
  "id": "3fd8634e78ca9560",
  "start_time": 1484872218.696,
  "end_time": 1484872218.697,
  "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
  "namespace": "remote",
  "sql" : {
    "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
    "preparation": "statement",
    "database_type": "PostgreSQL",
    "database_version": "9.5.4",
    "driver_version": "PostgreSQL 9.4.1211.jre7",
    "user" : "dbuser",
    "sanitized_query" : "SELECT  *  FROM  customers  WHERE  customer_id=?;"
  }
}