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.
# Utiliser l'API X-Ray
Si le SDK X-Ray ne prend pas en charge votre langage de programmation, vous pouvez utiliser le X-Ray APIs directement ou le AWS Command Line Interface (AWS CLI) pour appeler les commandes de l'API X-Ray. Suivez les instructions suivantes pour choisir la manière dont vous interagissez avec l'API :
+ Utilisez le AWS CLI pour une syntaxe plus simple à l'aide de commandes préformatées ou d'options dans votre requête.
+ Utilisez directement l'API X-Ray pour une flexibilité et une personnalisation maximales des demandes que vous envoyez à X-Ray.
Si vous utilisez directement l'[API X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) au lieu du AWS CLI, vous devez paramétrer votre demande dans le format de données approprié et vous devrez peut-être également configurer l'authentification et la gestion des erreurs.
Le schéma suivant indique comment choisir le mode d'interaction avec l'API X-Ray :
![\[X-Ray affiche des informations détaillées sur les demandes de candidature.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/api-vs-cli.png)
Utilisez l'API X-Ray pour envoyer les données de suivi directement à X-Ray. L'API X-Ray prend en charge toutes les fonctions disponibles dans le SDK X-Ray, y compris les actions courantes suivantes :
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)— Télécharge les documents segmentés sur X-Ray.
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html)— Récupère une liste de traces dans une liste de traces IDs. Chaque trace récupérée est une collection de documents segmentés provenant d'une seule demande.
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)— Récupère IDs et annote les traces. Vous pouvez spécifier a `FilterExpression` pour récupérer un sous-ensemble de résumés de traces.
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html)— Récupère un graphique de service pour un ID de trace spécifique.
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)— Récupère un JSON document formaté qui décrit les services qui traitent les demandes entrantes et appellent les demandes en aval.
Vous pouvez également utiliser le AWS Command Line Interface (AWS CLI) dans le code de votre application pour interagir par programmation avec X-Ray. Il AWS CLI prend en charge toutes les fonctions disponibles dans le SDK X-Ray, y compris celles pour les autres Services AWS. Les fonctions suivantes sont des versions des opérations d'API répertoriées précédemment dans un format plus simple :
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html)— Télécharge les documents segmentés sur X-Ray.
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html)— Récupère une liste de traces dans une liste de traces IDs. Chaque trace récupérée est une collection de documents segmentés provenant d'une seule demande.
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html)— Récupère IDs et annote les traces. Vous pouvez spécifier a `FilterExpression` pour récupérer un sous-ensemble de résumés de traces.
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html)— Récupère un graphique de service pour un ID de trace spécifique.
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html)— Récupère un document `JSON` formaté qui décrit les services qui traitent les demandes entrantes et appellent les demandes en aval.
Pour commencer, vous devez installer le [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)pour votre système d'exploitation. AWS soutient Linux, macOS and Windows systèmes d'exploitation. Pour plus d'informations sur la liste des commandes X-Ray, consultez le [guide AWS CLI Command Reference pour X-Ray](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html).
**Topics**
+ [Utilisation de l' AWS X-Ray API avec la AWS CLI](xray-api-tutorial.md)
+ [Envoi de données de suivi à AWS X-Ray](xray-api-sendingdata.md)
+ [Obtenir des données à partir de AWS X-Ray](xray-api-gettingdata.md)
+ [Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec l' AWS X-Ray API](xray-api-configuration.md)
+ [Utilisation de règles d'échantillonnage avec l'API X-Ray](xray-api-sampling.md)
+ [AWS X-Ray documents segmentés](xray-api-segmentdocuments.md)
# Utilisation de l' AWS X-Ray API avec la AWS CLI
La AWS CLI vous permet d'accéder directement au service X-Ray et d'utiliser le même APIs que celui utilisé par la console X-Ray pour récupérer le graphe du service et les données de trace brutes. L'exemple d'application inclut des scripts qui montrent comment les utiliser APIs avec la AWS CLI.
## Prérequis
Ce didacticiel utilise l'exemple d'application Scorekeep et inclut des scripts pour générer des données de suivi et une cartographie des services. Suivez les instructions du [didacticiel de mise en route](xray-gettingstarted.md) pour lancer l'application.
Ce didacticiel utilise le AWS CLI pour montrer l'utilisation de base de l'API X-Ray. La AWS CLI, [disponible pour Windows, Linux et OS-X](https://docs.aws.amazon.com/cli/latest/userguide/installing.html), fournit un accès en ligne de commande au public APIs pour tous. Services AWS
**Note**
Vous devez vérifier que vous êtes AWS CLI configuré dans la même région que celle dans laquelle votre exemple d'application Scorekeep a été créé.
Les scripts inclus pour tester l'exemple d'application utilisent `cURL` pour envoyer le trafic vers l'API et `jq` pour analyser la sortie. Vous pouvez télécharger l' exécutable à`jq` partir de [stedolan.github.io](https://stedolan.github.io/jq/) et l' exécutable `curl` à partir de [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html). La plupart des installations Linux et OS X incluent cURL.
## Génération de données de suivi
L'application web continue de générer du trafic vers l'API à intervalles réguliers de quelques secondes pendant que le jeu est en cours, mais elle génère uniquement un type de demande. Utilisez le script `test-api.sh` pour exécuter des scénarios de bout en bout et générer plusieurs autres données de suivi pendant que vous testez l'API.
**Pour utiliser le script `test-api.sh`**
1. Ouvrez la [console Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Accédez à la [console de gestion](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) de votre environnement.
1. Copiez l'**URL** de l'environnement à partir de l'en-tête de page.
1. Ouvrez `bin/test-api.sh` et remplacez la valeur pour l'API par l'URL de votre environnement.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. Exécutez le script pour générer du trafic vers l'API.
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating users,
session,
game,
configuring game,
playing game,
ending game,
game complete.
{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
```
## Utiliser l'API X-Ray
La AWS CLI fournit des commandes pour toutes les actions d'API proposées par X-Ray, y compris [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)et [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Consultez le document [Référence d'API AWS X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) pour plus d'informations sur toutes les actions prises en charge et les types de données utilisés.
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
Le script récupère un graphique de services pour les 10 dernières minutes.
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
Le script récupère les URLs traces générées il y a une à deux minutes.
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
Le script récupère les suivis entiers générés il y a une et deux minutes.
```
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
```
## Nettoyage
Mettez fin à votre environnement Elastic Beanstalk pour arrêter les instances EC2 Amazon, les tables DynamoDB et les autres ressources.
**Pour arrêter votre environnement Elastic Beanstalk**
1. Ouvrez la [console Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Accédez à la [console de gestion](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) de votre environnement.
1. Choisissez **Actions**.
1. Choisissez **Terminate Environment (Terminer l'environnement)**.
1. Sélectionnez **Résilier**.
Les données de suivi sont automatiquement supprimées de X-Ray au bout de 30 jours.
# Envoi de données de suivi à AWS X-Ray
Vous pouvez envoyer des données de suivi à X-Ray sous forme de documents segmentés. Un document de segment est une chaîne au format JSON contenant des informations sur les tâches effectuées par votre application pour répondre à une demande. Votre application peut enregistrer des données sur les tâches qu'elle effectue elle-même dans les segments, ou sur celles qui font appel à des ressources et services en aval dans les sous-segments.
Les segments enregistrent les informations sur les tâches effectuées par votre application. Au minimum, un segment enregistre le temps passé sur une tâche, un nom, IDs etc. L'ID de suivi permet de suivre la demande lors de son cheminement entre les différents services. L'ID de segment permet de suivre les tâches effectuées par un service en particulier pour répondre à la demande.
**Example Segment terminé minimal**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Lors de la réception d'une demande, vous pouvez envoyer un segment en cours comme espace réservé en attendant la réponse.
**Example Segment en cours**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
Vous pouvez envoyer des segments à X-Ray directement [`PutTraceSegments`](#xray-api-segments), avec ou [via le daemon X-Ray](#xray-api-daemon).
La plupart des applications appellent d'autres services ou accèdent à des ressources à l'aide du AWS SDK. Enregistrez les informations relatives aux appels en aval dans des *sous-segments*. X-Ray utilise des sous-segments pour identifier les services en aval qui n'envoient pas de segments et créer des entrées pour eux sur le graphique des 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 pour suivre de manière asynchrone les appels en aval pour les demandes de longue durée ou pour éviter de dépasser la taille maximale du document de segment (64 kB).
**Example Sous-segment**
Un sous-segment possède un `type` de `subsegment` et un `parent_id` qui identifie le segment parent.
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
Pour plus d'informations sur les champs et les valeurs que vous pouvez inclure dans les segments et les sous-segments, consultez [AWS X-Ray documents segmentés](xray-api-segmentdocuments.md).
**Topics**
+ [Génération d'une trace IDs](#xray-api-traceids)
+ [En utilisant PutTraceSegments](#xray-api-segments)
+ [Envoi de documents segmentés au daemon X-Ray](#xray-api-daemon)
## Génération d'une trace IDs
Pour envoyer des données à X-Ray, vous devez générer un identifiant de trace unique pour chaque demande.
**Format d'identification X-Ray Trace**
Un X-Ray `trace_id` est composé de trois chiffres séparés par des tirets. Par exemple, `1-58406520-a006649127e371903a2de979`. Cela inclut notamment les éléments suivants :
+ Le numéro de version, qui est`1`.
+ L'heure de la demande d'origine sous Unix Epoch Time en utilisant **8 chiffres hexadécimaux**.
Par exemple, le 1er décembre 2016 à 10 h 00 PST est exprimé en `1480615200` secondes ou `58406520` en chiffres hexadécimaux.
+ Identifiant 96 bits unique au monde pour la trace en **24 chiffres hexadécimaux**.
**Note**
X-Ray prend désormais en charge IDs les traces créées à OpenTelemetry l'aide de tout autre framework conforme à la spécification [W3C Trace Context](https://www.w3.org/TR/trace-context/). Un ID de trace W3C doit être formaté au format X-Ray Trace ID lors de son envoi à X-Ray. Par exemple, l'ID de trace du W3C `4efaaf4d1e8720b39541901950019ee5` doit être formaté comme `1-4efaaf4d-1e8720b39541901950019ee5` lorsqu'il est envoyé à X-Ray. X-Ray Trace IDs inclut l'horodatage de la demande d'origine dans Unix Epoch Time, mais cela n'est pas obligatoire lors de l'envoi de la trace W3C au format IDs X-Ray.
Vous pouvez écrire un script pour générer un tracé X-Ray à des IDs fins de test. Voici deux exemples :
**Python**
```
import time
import os
import binascii
START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
```
**Bash**
```
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
```
Consultez l'exemple d'application Scorekeep pour découvrir les scripts qui créent des traces IDs et envoient des segments au daemon X-Ray.
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash — [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## En utilisant PutTraceSegments
Vous pouvez charger des documents relatifs aux segments avec l'API [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html). L'API possède un seul paramètre, `TraceSegmentDocuments`, qui accepte une liste de documents de segment au format JSON.
Avec l'AWS CLI, utilisez la `aws xray put-trace-segments` commande pour envoyer les documents de segment directement à X-Ray.
```
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
"UnprocessedTraceSegments": []
}
```
**Note**
Le processeur de commandes Windows et Windows PowerShell ont des exigences différentes en matière de guillemets et d'échappements aux guillemets dans les chaînes JSON. Pour plus d'informations, consultez [Indication des chaînes entre guillemets](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings) dans le Guide de l'utilisateur de l' AWS CLI .
La sortie répertorie tous les segments dont le traitement a échoué. Par exemple, si la date qui figure dans l'ID de suivi remonte à trop loin, une erreur similaire à la suivante s'affiche :
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
Vous pouvez indiquer plusieurs documents de segment à la suite, en les séparant par des espaces.
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## Envoi de documents segmentés au daemon X-Ray
Au lieu d'envoyer des documents de segment à l'API X-Ray, vous pouvez envoyer des segments et des sous-segments au daemon X-Ray, qui les mettra en mémoire tampon et les téléchargera par lots vers l'API X-Ray. Le SDK X-Ray envoie des documents segmentés au daemon afin d'éviter de passer des appels directs à AWS celui-ci.
**Note**
Consultez [Exécution du daemon X-Ray en local](xray-daemon-local.md) pour obtenir des instructions sur l'exécution du démon.
Envoyez le segment au format JSON sur le port UDP 2000, en ajoutant en préfixe l'en-tête du démon, `{"format": "json", "version": 1}\n`
```
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
```
Sous Linux, vous pouvez envoyer des documents de segment au démon depuis un terminal Bash. Enregistrez l'en-tête et le document de segment comme fichier texte et placez-les dans `/dev/udp` avec `cat`.
```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```
**Example segment.txt**
```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```
Consultez le [journal du démon](xray-daemon.md#xray-daemon-logging) pour vérifier qu'il a envoyé le segment à X-Ray.
```
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
```
# Obtenir des données à partir de AWS X-Ray
AWS X-Ray traite les données de suivi que vous lui envoyez pour générer des traces complètes, des résumés de traces et des graphiques de service au format JSON. Vous pouvez récupérer les données générées directement depuis l'API à l'aide de la AWS CLI.
**Topics**
+ [Récupération du graphique de services](#xray-api-servicegraph)
+ [Récupération du graphique des services par groupe](#xray-api-servicegraphgroup)
+ [Récupération des suivis](#xray-api-traces)
+ [Extraction et affinage de l'analyse de la cause racine](#xray-api-analytics)
## Récupération du graphique de services
Vous pouvez utiliser l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) pour récupérer le graphique de services JSON. L'API nécessite une heure de début et de fin, que vous pouvez calculer à partir d'un terminal Linux avec la commande `date`.
```
$ date +%s
1499394617
```
`date +%s` détermine une date en quelques secondes. Utilisez cette valeur comme une heure de fin et déduisez le temps de traitement pour obtenir une heure de début.
**Example Script permettant de récupérer un graphique de services pour les 10 dernières minutes**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
L'exemple suivant montre un graphe de service avec 4 nœuds, dont un nœud client, une EC2 instance, une table DynamoDB et une rubrique Amazon SNS.
**Example GetServiceGraph sortie**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## Récupération du graphique des services par groupe
Pour appeler un graphique des services en fonction du contenu d'un groupe, incluez un élément `groupName` ou `groupARN`. L'exemple suivant illustre un appel de graphique des services à un groupe nommé Example1.
**Example Script permettant de récupérer un graphique des services par nom pour le groupe Example1**
```
aws xray get-service-graph --group-name "Example1"
```
## Récupération des suivis
Vous pouvez utiliser l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) pour obtenir la liste des synthèses de suivi. Les résumés de traces incluent des informations que vous pouvez utiliser pour identifier les traces que vous souhaitez télécharger dans leur intégralité, notamment les annotations, les informations de demande et de réponse, et. IDs
Il y a deux indicateurs `TimeRangeType` disponibles lors de l'appel de `aws xray get-trace-summaries` :
+ **TraceId**— La `GetTraceSummaries` recherche par défaut utilise l'heure de TraceID et renvoie les traces démarrées dans la plage calculée`[start_time, end_time)`. Cette plage d'horodatages est calculée en fonction du codage de l'horodatage dans le TraceId, ou peut être définie manuellement.
+ **Durée de l'événement** : pour rechercher les événements tels qu'ils se produisent au fil du temps, AWS X-Ray permet de rechercher des traces à l'aide des horodatages des événements. L'heure de l'événement renvoie les traces actives au cours de la plage `[start_time, end_time)`, quel que soit le moment où la trace a commencé.
Utilisez la commande `aws xray get-trace-summaries` pour obtenir la liste des synthèses de suivi. Les commandes suivantes permettent d'obtenir une liste de résumés de traces réalisés il y a 1 à 2 minutes en utilisant l' TraceIdheure par défaut.
**Example Script permettant d'obtenir des synthèses de suivi**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries sortie**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
Utilisez l'ID de suivi de la sortie pour obtenir un suivi complet avec l'API [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html).
**Example BatchGetTraces commande**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces sortie**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
Le suivi complet inclut un document pour chaque segment, compilé à partir de l'ensemble des documents de segments reçus pour le même ID de suivi. Ces documents ne représentent pas les données telles qu'elles ont été envoyées à X-Ray par votre application. Ils représentent plutôt les documents traités générés par le service X-Ray. X-Ray crée le document de trace complet en compilant les documents de segment envoyés par votre application et en supprimant les données non conformes au [schéma du document de segment](xray-api-segmentdocuments.md).
X-Ray crée également des *segments déduits* pour les appels en aval vers des services qui n'envoient pas de segments eux-mêmes. Par exemple, lorsque vous appelez DynamoDB avec un client instrumenté, le SDK X-Ray enregistre un sous-segment contenant des détails sur l'appel du point de vue de celui-ci. Cependant, DynamoDB n'envoie pas de segment correspondant. X-Ray utilise les informations du sous-segment pour créer un segment inféré représentant la ressource DynamoDB dans la carte de trace, et l'ajoute au document de trace.
Pour obtenir plusieurs traces à partir de l'API, vous avez besoin d'une liste de traces IDs, que vous pouvez extraire du résultat à l'`get-trace-summaries`aide d'une [AWS CLI requête](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter). Redirigez la liste vers l'entrée de `batch-get-traces` pour obtenir des traces complètes pour une période spécifique.
**Example Script permettant d'obtenir les suivis complets pour une période d'une minute**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
## Extraction et affinage de l'analyse de la cause racine
Lors de la génération d'un résumé de trace avec l'[GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html), les résumés de suivi partiels peuvent être réutilisés dans leur format JSON pour créer une expression de filtre affinée basée sur les causes premières. Consultez les exemples ci-dessous pour connaître les étapes d’affinage.
**Example Exemple GetTraceSummaries de sortie : section sur la cause première du temps de réponse**
```
{
"Services": [
{
"Name": "GetWeatherData",
"Names": ["GetWeatherData"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetWeatherData",
"Coverage": 1.0,
'Remote": false
},
{
"Name": "get_temperature",
"Coverage": 0.8,
"Remote": false
}
]
},
{
"Name": "GetTemperature",
"Names": ["GetTemperature"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetTemperature",
"Coverage": 0.7,
"Remote": false
}
]
}
]
}
```
En modifiant la sortie ci-dessus ou en lui appliquant des omissions, ce fichier JSON peut devenir un filtre pour les entités de cause racine correspondantes. Pour chaque champ de cette sortie JSON, les correspondances de candidat doivent être exactes pour que le suivi soit renvoyé. Les champs supprimés deviennent des valeurs de caractères génériques, ce qui correspond à un format compatible avec la structure de requête de l’expression de filtre.
**Example Cause racine des temps de réponse reformatée**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
Ce format JSON est ensuite utilisé en tant que partie d’une expression de filtre via un appel à `rootcause.json = #[{}]`. Consultez le chapitre sur les [expressions de filtre](xray-console-filters.md) pour en savoir plus sur l’exécution de requêtes avec des expressions de filtre.
**Example Exemple de filtre JSON**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec l' AWS X-Ray API
AWS X-Ray permet APIs de configurer les [règles d'échantillonnage, les](xray-console-sampling.md) règles de groupe et les [paramètres de chiffrement](xray-console-encryption.md).
**Topics**
+ [Paramètres de chiffrement](#xray-api-configuration-encryption)
+ [Règles d'échantillonnage](#xray-api-configuration-sampling)
+ [Groupes](#xray-api-configuration-groups)
## Paramètres de chiffrement
Permet [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)de spécifier une clé AWS Key Management Service (AWS KMS) à utiliser pour le chiffrement.
**Note**
X-Ray ne prend pas en charge les clés KMS asymétriques.
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
Pour l'ID de clé, vous pouvez utiliser un alias (comme illustré dans l'exemple), un ID de clé ou un ARN.
Utilisez [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) pour obtenir la configuration actuelle. Lorsque X-Ray a fini d'appliquer vos paramètres, le statut passe de `UPDATING` à`ACTIVE`.
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
Pour arrêter d'utiliser une clé KMS et utiliser le chiffrement par défaut, définissez le type de chiffrement sur`NONE`.
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## Règles d'échantillonnage
Vous pouvez gérer les [règles d'échantillonnage](xray-console-sampling.md) de votre compte à l'aide de l'API X-Ray. Pour plus d'informations sur l'ajout et la gestion de balises, consultez[Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
Obtenez toutes les règles d'échantillonnage avec [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
Par défaut, la règle s'applique à toutes les demandes qui ne correspond à aucune autre règle. Elle est la règle avec la plus faible priorité et ne peut pas être supprimée. Toutefois, vous pouvez modifier la fréquence et la taille du réservoir avec [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html).
**Example Entrée d'API pour [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
L'exemple suivant utilise le fichier précédente en tant qu'entrée pour modifier la règle par défaut sur un pour cent (1 %) sans réservoir. Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives. Pour supprimer des balises existantes d'une règle d'échantillonnage, utilisez [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
Créez les règles d'échantillonnage supplémentaires avec [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html). Lorsque vous créez une règle, la plupart des champs de la règle sont obligatoires. L'exemple suivant crée deux règles. Cette première règle définit un taux de base pour l'exemple d'application Scorekeep. Elle correspond à toutes les demandes servies par l'API qui ne correspond pas à la priorité de la règle.
**Example Entrée d'API pour [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 9000-base-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
La deuxième règle s'applique également à Scorekeep, mais elle a une priorité plus élevée et est plus spécifique. Cette règle définit un très faible taux d'échantillonnage pour les demandes d'interrogation. Il s'agit de demandes GET effectuées par le client toutes les deux ou trois secondes pour rechercher les modifications apportées à l'état du jeu.
**Example Entrée d'API pour [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 5000-polling-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives.
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
Pour supprimer une règle d'échantillonnage, utilisez [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html).
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## Groupes
Vous pouvez utiliser l'API X-Ray pour gérer les groupes de votre compte. Les groupes sont un ensemble de traces définies par une expression de filtre. Vous pouvez utiliser des groupes pour générer des graphiques de service supplémentaires et fournir CloudWatch des statistiques Amazon. Consultez [Obtenir des données à partir de AWS X-Ray](xray-api-gettingdata.md) pour plus de détails sur l'utilisation des graphiques et des métriques de service via l'API X-Ray. Pour plus d'informations sur les groupes, consultez[Configuration des groupes](xray-console-groups.md). Pour plus d'informations sur l'ajout et la gestion de balises, consultez[Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
Création d'un groupe avec `CreateGroup` Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives.
```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Obtenez tous les groupes existants à l'aide de `GetGroups`.
```
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}
```
Mettez à jour un groupe à l'aide de `UpdateGroup`. Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives. Pour supprimer des balises existantes d'un groupe, utilisez [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html).
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Supprimez un groupe à l'aide de `DeleteGroup`.
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# Utilisation de règles d'échantillonnage avec l'API X-Ray
Le AWS X-Ray SDK utilise l'API X-Ray pour obtenir des règles d'échantillonnage, communiquer les résultats d'échantillonnage et obtenir des quotas. Vous pouvez les utiliser APIs pour mieux comprendre le fonctionnement des règles d'échantillonnage ou pour implémenter l'échantillonnage dans un langage non pris en charge par le kit de développement X-Ray.
Commencez par obtenir toutes les règles d'échantillonnage avec [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
La sortie inclut la règle par défaut et les règles personnalisées. Consultez [Règles d'échantillonnage](xray-api-configuration.md#xray-api-configuration-sampling) si vous n'avez pas encore créé de règles d'échantillonnage.
Evaluez les règles par rapport aux demandes entrantes par ordre croissant de priorité. Lorsqu'une règle correspond, utilisez la fréquence et la taille de réservoir fixées pour prendre une décision d'échantillonnage. Enregistrez les demandes échantillonnées et ignorez (à des fins de suivi) les demandes non échantillonnées. Arrêtez l'évaluation des règles lorsqu'une décision d'échantillonnage est prise.
Une taille de réservoir de règles est le nombre cible de suivis à enregistrer par seconde avant d'appliquer la fréquence fixe. Le réservoir s'applique à tous les services cumulativement. Vous ne pouvez donc pas l'utiliser directement. Toutefois, s'il est différent de zéro, vous pouvez emprunter une trace par seconde dans le réservoir jusqu'à ce que X-Ray vous assigne un quota. Avant de recevoir un quota, enregistrez la première demande chaque seconde et appliquez le taux fixe aux demandes additionnelles. La fréquence fixe est un nombre décimal compris entre 0 et 1,00 (100 %).
L'exemple suivant illustre un appel à [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) avec les détails sur les décisions d'échantillonnage effectuées au cours des 10 dernières secondes.
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
La réponse de X-Ray inclut un quota à utiliser au lieu d'emprunter au réservoir. Dans cet exemple, le service a emprunté 10 suivis au réservoir sur 10 secondes et appliqué la fréquence fixe de 10 % aux 100 autres demandes, ce qui se traduit par un total de 20 demandes échantillonnées. Le quota est valable pendant cinq minutes (indiqué par l'heure de vie) ou jusqu'à ce qu'un nouveau quota soit attribué. X-Ray peut également attribuer un intervalle de rapport plus long que celui par défaut, bien que ce ne soit pas le cas ici.
**Note**
La réponse de X-Ray n'inclut peut-être pas de quota la première fois que vous l'appelez. Continuez à emprunter au réservoir jusqu'à ce qu'un quota vous sot attribué.
Les deux autres champs de la réponse peuvent indiquer des problèmes avec l'entrée. Vérifiez `LastRuleModification` par rapport à votre dernier appel de [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html). S'il est plus récent, obtenez une nouvelle copie des règles. `UnprocessedStatistics` peut inclure des erreurs qui indiquent qu'une règle a été supprimée, que les statistiques de document dans l'entrée étaient trop anciennes ou qu'elle comportait des erreurs d'autorisation.
# AWS X-Ray documents segmentés
Un **segment de suivi** est une représentation JSON d'une demande que sert votre application. Un segment de trace enregistre des informations sur la demande d'origine, des informations sur le travail effectué localement par votre application et des **sous-segments contenant** des informations sur les appels en aval que votre application effectue vers les AWS ressources, les bases de données HTTP APIs et SQL.
Un **document de segment** transmet des informations sur un segment à X-Ray. Un document segmenté peut peser jusqu'à 64 kB et contenir un segment entier avec des sous-segments, un fragment de segment indiquant qu'une demande est en cours ou un sous-segment unique envoyé séparément. Vous pouvez envoyer des documents de segment directement à X-Ray à l'aide de l'[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)API.
X-Ray compile et traite des documents segmentés pour générer des **résumés de traces interrogeables et des** **traces complètes auxquels** vous pouvez accéder en utilisant respectivement le [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)et. [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) APIs Outre les segments et sous-segments que vous envoyez à X-Ray, le service utilise les informations contenues dans les sous-segments pour générer des **segments déduits** et les ajouter à la trace complète. Les segments déduits représentent les services et les ressources en aval sur la carte de suivi.
X-Ray fournit un **schéma JSON** pour les documents segmentés. Vous pouvez télécharger le schéma ici : [xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip). 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 X-Ray pour être utilisé avec des expressions de filtre. Par exemple, si vous attribuez un identifiant unique au `user` champ d'un segment, vous pouvez rechercher des segments associés à des utilisateurs spécifiques dans la console X-Ray ou à l'aide de l'`GetTraceSummaries`API. Pour de plus amples informations, veuillez consulter [Utilisation d'expressions de filtre](xray-console-filters.md).
Lorsque vous instrumentez votre application avec le SDK X-Ray, celui-ci génère des documents segmentés pour vous. Au lieu d'envoyer les documents segmentés directement à X-Ray, le SDK les transmet via un port UDP local au daemon [X-Ray](xray-daemon.md). Pour de plus amples informations, veuillez consulter [Envoi de documents segmentés au daemon X-Ray](xray-api-sendingdata.md#xray-api-daemon).
**Topics**
+ [Champs de segment](#api-segmentdocuments-fields)
+ [Sous-segments](#api-segmentdocuments-subsegments)
+ [Données de demande HTTP](#api-segmentdocuments-http)
+ [Annotations](#api-segmentdocuments-annotations)
+ [Métadonnées](#api-segmentdocuments-metadata)
+ [AWS données sur les ressources](#api-segmentdocuments-aws)
+ [Erreurs et exceptions](#api-segmentdocuments-errors)
+ [Requêtes SQL](#api-segmentdocuments-sql)
## 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.
**Example 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, **200 caractères** maximum. 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`— Un identifiant 64 bits pour le segment, unique parmi les segments d'une même trace, en **16 chiffres hexadécimaux**.
+ `trace_id`— Un identifiant unique qui connecte tous les segments et sous-segments issus d'une seule demande client.
**Format d'identification X-Ray Trace**
Un X-Ray `trace_id` est composé de trois chiffres séparés par des tirets. Par exemple, `1-58406520-a006649127e371903a2de979`. Cela consiste notamment à :
+ Le numéro de version, qui est`1`.
+ L'heure de la demande initiale sous Unix Epoch Time en utilisant **8 chiffres hexadécimaux**.
Par exemple, le 1er décembre 2016 à 10 h 00 PST est exprimé en `1480615200` secondes ou `58406520` en chiffres hexadécimaux.
+ Identifiant 96 bits unique au monde pour la trace en **24 chiffres hexadécimaux**.
**Note**
X-Ray prend désormais en charge IDs les traces créées à OpenTelemetry l'aide de tout autre framework conforme à la spécification [W3C Trace Context](https://www.w3.org/TR/trace-context/). Un identifiant de trace W3C doit être formaté au format X-Ray trace ID lors de son envoi à X-Ray. Par exemple, l'ID de trace du W3C `4efaaf4d1e8720b39541901950019ee5` doit être formaté comme `1-4efaaf4d-1e8720b39541901950019ee5` lorsqu'il est envoyé à X-Ray. X-Ray Trace IDs inclut l'horodatage de la demande d'origine dans Unix Epoch Time, mais cela n'est pas obligatoire lors de l'envoi de la trace W3C au format IDs X-Ray.
**Sécurité de l'ID de suivi**
IDs Les traces sont visibles dans les [en-têtes de réponse](xray-concepts.md#xray-concepts-tracingheader). Générez des traces IDs à l'aide d'un algorithme aléatoire sécurisé pour empêcher les attaquants de calculer les traces futures IDs et d'envoyer des demandes avec celles-ci IDs à votre application.
+ `start_time`— **nombre correspondant** à l'heure à laquelle le segment a été créé, en secondes à virgule flottante par rapport à l'époque. 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`— **numéro correspondant** à l'heure à laquelle 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 sur au `true` lieu de spécifier un `end_time` pour enregistrer qu'un segment est 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.
**Noms des services**
Un segment `name` doit 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 autorisée [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)peut envoyer des segments sous n'importe quel nom.
Les champs suivants sont facultatifs pour les segments.
**Champs de segment facultatifs**
+ `service`— Un objet contenant des informations sur votre application.
+ `version`— Chaîne identifiant la version de votre application qui a répondu à la demande.
+ `user`— Chaîne identifiant l'utilisateur qui a envoyé la demande.
+ `origin`— Type de AWS ressource exécutant votre application.
**Valeurs prises en charge**
+ `AWS::EC2::Instance`— Une EC2 instance Amazon.
+ `AWS::ECS::Container`— Un conteneur Amazon ECS.
+ `AWS::ElasticBeanstalk::Environment`— Un 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 multicontainer 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`— Un ID de sous-segment que vous spécifiez si la demande provient d'une application instrumentée. Le SDK X-Ray ajoute l'ID du sous-segment parent à l'[en-tête de suivi](xray-concepts.md#xray-concepts-tracingheader) pour 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`— [`http`](#api-segmentdocuments-http)objets contenant des informations sur la requête HTTP d'origine.
+ `aws`— [`aws`](#api-segmentdocuments-aws)objet contenant des informations sur la AWS ressource sur laquelle votre application a envoyé la demande.
+ `error`,`throttle`,`fault`, et `cause` — champs [d'erreur](#api-segmentdocuments-errors) qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception à l'origine de l'erreur.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)objet avec des paires clé-valeur que vous souhaitez que X-Ray indexe pour la recherche.
+ `metadata`: [`metadata`](#api-segmentdocuments-metadata)objet contenant toutes les données supplémentaires que vous souhaitez stocker dans le segment.
+ `subsegments`— **ensemble** d'[`subsegment`](#api-segmentdocuments-subsegments)objets.
## Sous-segments
Vous pouvez créer des sous-segments pour enregistrer les appels Services AWS et les ressources que vous effectuez avec le AWS SDK, les appels vers le Web APIs HTTP interne ou externe ou les requêtes de base de données SQL. 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 les services en aval qui n'envoient pas de segments et créer des entrées pour eux sur le graphique des 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.
**Example 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 en cours pour informer X-Ray de la réception de la demande, puis envoyer des sous-segments séparément pour les suivre avant de terminer la demande initiale.
**Example Segment en cours**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 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 est envoyée, suivi de sous-segments pour le travail terminé 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`— Un identifiant de 64 bits pour le sous-segment, unique parmi les segments d'une même trace, en **16 chiffres hexadécimaux**.
+ `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`— **nombre correspondant** à l'heure à laquelle le sous-segment a été créé, en secondes à virgule flottante par rapport à l'époque, avec une précision de quelques millisecondes. Par exemple, `1480615200.010` ou `1.480615200010E9`.
+ `end_time`— **numéro correspondant** à l'heure à laquelle le sous-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 sur `true` au lieu de spécifier un `end_time` pour enregistrer qu'un sous-segment est 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 trace du segment parent du sous-segment. Obligatoire uniquement en cas d'envoi séparé d'un sous-segment.
**Format d'identification X-Ray Trace**
Un X-Ray `trace_id` est composé de trois chiffres séparés par des tirets. Par exemple, `1-58406520-a006649127e371903a2de979`. Cela consiste notamment à :
+ Le numéro de version, qui est`1`.
+ L'heure de la demande initiale sous Unix Epoch Time en utilisant **8 chiffres hexadécimaux**.
Par exemple, le 1er décembre 2016 à 10 h 00 PST est exprimé en `1480615200` secondes ou `58406520` en chiffres hexadécimaux.
+ Identifiant 96 bits unique au monde pour la trace en **24 chiffres hexadécimaux**.
**Note**
X-Ray prend désormais en charge IDs les traces créées à OpenTelemetry l'aide de tout autre framework conforme à la spécification [W3C Trace Context](https://www.w3.org/TR/trace-context/). Un identifiant de trace W3C doit être formaté au format X-Ray trace ID lors de son envoi à X-Ray. Par exemple, l'ID de trace du W3C `4efaaf4d1e8720b39541901950019ee5` doit être formaté comme `1-4efaaf4d-1e8720b39541901950019ee5` lorsqu'il est envoyé à X-Ray. X-Ray Trace IDs inclut l'horodatage de la demande d'origine dans Unix Epoch Time, mais cela n'est pas obligatoire lors de l'envoi de la trace W3C au format IDs X-Ray.
+ `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 si vous envoyez un sous-segment séparément.
Les champs suivants sont facultatifs pour les sous-segments.
**Champs de sous-segment facultatifs**
+ `namespace`— `aws` pour les appels du SDK AWS ; `remote` pour les autres appels en aval.
+ `http`— [`http`](#api-segmentdocuments-http)objet contenant des informations relatives à un appel HTTP sortant.
+ `aws`: [`aws`](#api-segmentdocuments-aws)objet contenant des informations sur la AWS ressource en aval appelée par votre application.
+ `error`,`throttle`,`fault`, et `cause` — champs [d'erreur](#api-segmentdocuments-errors) qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception à l'origine de l'erreur.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)objet avec des paires clé-valeur que vous souhaitez que X-Ray indexe pour la recherche.
+ `metadata`: [`metadata`](#api-segmentdocuments-metadata)objet contenant toutes les données supplémentaires que vous souhaitez stocker dans le segment.
+ `subsegments`— **ensemble** d'[`subsegment`](#api-segmentdocuments-subsegments)objets.
+ `precursor_ids`— **tableau** de sous-segments identifiant IDs les sous-segments ayant le même parent que ceux terminés 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 relatives à une demande.
+ `method`— La méthode de demande. Par exemple, `GET`.
+ `url`— L'URL complète de la demande, compilée à partir du protocole, du nom d'hôte et du chemin de la demande.
+ `user_agent`— La chaîne d'agent utilisateur du client du demandeur.
+ `client_ip`— L'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éen** indiquant que le `client_ip` a été lu à partir d'un `X-Forwarded-For` en-tête et qu'il n'est pas fiable car il aurait pu être falsifié.
+ `traced`— (sous-segments uniquement) **booléen** indiquant que l'appel en aval concerne un autre service suivi. Si ce champ est défini sur`true`, X-Ray considère que la trace est interrompue jusqu'à ce que le service en aval télécharge un segment dont le `parent_id` nom correspond à celui `id` du sous-segment contenant ce bloc.
+ `response`— Informations relatives à une réponse.
+ `status`— **entier** indiquant le statut HTTP de la réponse.
+ `content_length`— **entier** indiquant la longueur du corps de la réponse en octets.
Lorsque vous instrumentez un appel à une API Web en aval, enregistrez un sous-segment contenant des informations sur la requête et la réponse HTTP. X-Ray utilise le sous-segment pour générer un segment inféré pour l'API distante.
**Example Segment pour un appel HTTP envoyé par une application exécutée 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
}
}
```
**Example 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
}
}
}
```
**Example 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 un `annotations` objet contenant un ou plusieurs champs indexés par X-Ray pour une utilisation avec des expressions de filtre. Les champs peuvent avoir des valeurs de type chaîne, numérique ou booléen (ni objet ni tableau). X-Ray indexe jusqu'à 50 annotations par trace.
**Example 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.
## Métadonnées
Les segments et sous-segments peuvent inclure un `metadata` objet contenant un ou plusieurs champs avec des valeurs de n'importe quel type, y compris des objets et des tableaux. X-Ray n'indexe pas les métadonnées et les valeurs peuvent être de n'importe quelle taille, tant que le document 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 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html). Les clés de champ (`debug`dans l'exemple suivant) commençant par `AWS.` sont réservées à l'utilisation par AWS-provided SDKs et par les clients.
**Example 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"
]
}
}
]
}
```
## AWS données sur les 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 multiconteneur sur Elastic Beanstalk peut contenir des informations sur l'instance Amazon, le conteneur EC2 Amazon ECS exécuté 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 autre Compte AWS, enregistrez l'identifiant du compte qui exécute votre application.
+ `cloudwatch_logs`— Tableau d'objets décrivant un seul groupe de CloudWatch logs.
+ `log_group`— Le nom du groupe de CloudWatch journaux.
+ `arn`— L'ARN du groupe de CloudWatch logs.
+ `ec2`— Informations sur une EC2 instance Amazon.
+ `instance_id`— L'ID d'instance de l' EC2 instance.
+ `instance_size`— Type d' EC2 instance.
+ `ami_id`— L'identifiant Amazon Machine Image.
+ `availability_zone`— La zone de disponibilité dans laquelle l'instance est exécutée.
+ `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`— L'ARN de votre instance de conteneur.
+ `eks`— Informations sur un cluster Amazon EKS.
+ `pod`— Le nom d'hôte de votre pod 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 trouverez ces informations dans un fichier nommé `/var/elasticbeanstalk/xray/environment.conf` sur 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 qui a répondu à la demande.
+ `deployment_id`— **numéro** indiquant l'ID du dernier déploiement réussi sur l'instance qui a répondu à la demande.
+ `xray`— Des métadonnées sur le type et la version de l'instrumentation utilisée.
+ `auto_instrumentation`— Booléen indiquant si l'instrumentation automatique a été utilisée (par exemple, l'agent Java).
+ `sdk_version`— Version du SDK ou de l'agent utilisé.
+ `sdk`— Le type de SDK.
**Example AWS bloc avec plugins**
```
"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 relatives aux ressources Services AWS et aux ressources auxquelles votre application accède. X-Ray utilise ces informations pour créer des segments déduits qui représentent les services en aval dans votre carte des services.
**`aws` (Sous-segments)**
Tous les champs sont facultatifs.
+ `operation`— Le nom de l'action d'API invoquée contre une ressource Service AWS or.
+ `account_id`— Si votre application accède aux ressources d'un autre compte ou envoie des segments vers un autre compte, enregistrez l'ID du compte propriétaire de la AWS ressource à laquelle votre application a accédé.
+ `region`— Si la ressource se trouve dans une région différente de celle 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, nom de la table.
**Example Sous-segment pour un appel à DynamoDB pour enregistrer un élément**
```
{
"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éen** indiquant qu'une erreur client s'est produite (le code d'état de la réponse était 4XX Client Error).
+ `throttle`— **booléen** indiquant qu'une demande a été limitée (le code d'état de la réponse était *429 demandes trop nombreuses*).
+ `fault`— **booléen** indiquant qu'une erreur de serveur s'est produite (le code d'état de 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`— Le chemin complet du répertoire de travail lorsque l'exception s'est produite.
+ `paths`— Le **tableau** des chemins d'accès aux bibliothèques ou aux modules utilisés lorsque l'exception s'est produite.
+ `exceptions`— Le **tableau** des objets d'**exception**.
Incluez les informations détaillées sur l'erreur dans un ou plusieurs objets **exception**.
**`exception`**
Tous les champs sont facultatifs.
+ `id`— Un identifiant de 64 bits pour l'exception, unique parmi les segments d'une même trace, en **16 chiffres hexadécimaux**.
+ `message`— Le message d'exception.
+ `type`— Le type d'exception.
+ `remote`— **booléen** indiquant que l'exception a été provoquée par une erreur renvoyée par un service en aval.
+ `truncated`— **entier** indiquant le nombre de cadres de pile qui sont omis dans le`stack`.
+ `skipped`— **entier** indiquant le nombre d'exceptions ignorées entre cette exception et son enfant, c'est-à-dire l'exception qu'elle a provoquée.
+ `cause`— ID d'exception du parent de l'exception, c'est-à-dire l'exception à l'origine de cette exception.
+ `stack`— **tableau d'**objets **StackFrame**.
Le cas échéant, enregistrez les informations relatives à la pile des appels dans les objets **stackFrame**.
**`stackFrame`**
Tous les champs sont facultatifs.
+ `path`— Le chemin relatif du fichier.
+ `line`— La ligne du fichier.
+ `label`— Le 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 les connexions à SQL Server ou à d'autres bases de données qui n'utilisent pas de chaînes de connexion URL, enregistrez la chaîne de connexion, à l'exception des mots de passe.
+ `url`— Pour une connexion à une base de données utilisant une chaîne de connexion URL, enregistrez l'URL, à l'exception des mots de passe.
+ `sanitized_query`— La requête de base de données, avec toutes les 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`— Le nom et le numéro de version du pilote du moteur de base de données utilisé par votre application.
+ `user`— Le nom d'utilisateur de la base de données.
+ `preparation`— `call` si la requête a utilisé un `PreparedCall` ; `statement` si la requête a utilisé `PreparedStatement` a.
**Example 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=?;"
}
}
```