Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Usa l'API X-Ray
Se l'SDK X-Ray non supporta il tuo linguaggio di programmazione, puoi utilizzare APIs direttamente X-Ray o AWS Command Line Interface ()AWS CLI per richiamare i comandi dell'API X-Ray. Utilizza le seguenti indicazioni per scegliere come interagire con l'API:
+ Utilizza la sintassi AWS CLI per una sintassi più semplice utilizzando comandi preformattati o con opzioni all'interno della richiesta.
+ Utilizza direttamente l'API X-Ray per la massima flessibilità e personalizzazione per le richieste che invii a X-Ray.
Se si utilizza direttamente l'[API X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) anziché AWS CLI, è necessario parametrizzare la richiesta nel formato di dati corretto e potrebbe anche essere necessario configurare l'autenticazione e la gestione degli errori.
Il diagramma seguente mostra le linee guida per scegliere come interagire con l'API X-Ray:
![\[X-Ray visualizza informazioni dettagliate sulle richieste delle applicazioni.\]](http://docs.aws.amazon.com/it_it/xray/latest/devguide/images/api-vs-cli.png)
Utilizza l'API X-Ray per inviare i dati di traccia direttamente a X-Ray. L'API X-Ray supporta tutte le funzioni disponibili in X-Ray SDK, incluse le seguenti azioni comuni:
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)— Carica i documenti dei segmenti su X-Ray.
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html)— Recupera un elenco di tracce in un elenco di tracce. IDs Ogni traccia recuperata è una raccolta di documenti di segmento provenienti da una singola richiesta.
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)— Recupera IDs e annota le tracce. È possibile specificare `FilterExpression` a per recuperare un sottoinsieme di riepiloghi delle tracce.
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html)— Recupera un grafico di servizio per un ID di traccia specifico.
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)— Recupera un JSON documento formattato che descrive i servizi che elaborano le richieste in entrata e le chiamano le richieste a valle.
Puoi anche usare il AWS Command Line Interface (AWS CLI) all'interno del codice dell'applicazione per interagire a livello di codice con X-Ray. AWS CLI Supporta tutte le funzioni disponibili nell'X-Ray SDK, comprese quelle per altri. Servizi AWS Le seguenti funzioni sono versioni delle operazioni API elencate in precedenza con un formato più semplice:
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html)— Carica i documenti dei segmenti su X-Ray.
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html)— Recupera un elenco di tracce in un elenco di tracce. IDs Ogni traccia recuperata è una raccolta di documenti di segmento provenienti da una singola richiesta.
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html)— Recupera IDs e annota le tracce. È possibile specificare `FilterExpression` a per recuperare un sottoinsieme di riepiloghi delle tracce.
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html)— Recupera un grafico di servizio per un ID di traccia specifico.
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html)— Recupera un documento `JSON` formattato che descrive i servizi che elaborano le richieste in entrata e chiamano le richieste a valle.
Per iniziare, è necessario installare il file [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)per il proprio sistema operativo. AWS supporti Linux, macOS e Windows sistemi operativi. Per ulteriori informazioni sull'elenco dei comandi X-Ray, vedere la [guida di riferimento ai AWS CLI comandi per X-Ray](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html).
**Topics**
+ [Utilizzo dell' AWS X-Ray API con la AWS CLI](xray-api-tutorial.md)
+ [Invio di dati di tracciamento a AWS X-Ray](xray-api-sendingdata.md)
+ [Ottenere dati da AWS X-Ray](xray-api-gettingdata.md)
+ [Configurazione delle impostazioni di campionamento, gruppi e crittografia con l'API AWS X-Ray](xray-api-configuration.md)
+ [Using sampling rules with the X-Ray API (Utilizzo delle regole di campionamento con l'API X-Ray)](xray-api-sampling.md)
+ [AWS X-Ray segmentare i documenti](xray-api-segmentdocuments.md)
# Utilizzo dell' AWS X-Ray API con la AWS CLI
La AWS CLI consente di accedere direttamente al servizio X-Ray e di utilizzare lo stesso che la console X-Ray utilizza per recuperare APIs il grafico del servizio e i dati grezzi delle tracce. L'applicazione di esempio include script che mostrano come utilizzarli APIs con la AWS CLI.
## Prerequisiti
Questo tutorial utilizza l'applicazione di esempio Scorekeep e gli script in essa inclusi per generare dei dati di tracciamento e una mappa del servizio. Segui le istruzioni nel [tutorial sulle nozioni di base](xray-gettingstarted.md) per avviare l'applicazione.
Questo tutorial utilizza AWS CLI per mostrare l'uso di base dell'API X-Ray. La AWS CLI, [disponibile per Windows, Linux e OS-X,](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) fornisce l'accesso da riga di comando al pubblico per tutti. APIs Servizi AWS
**Nota**
È necessario verificare che sia configurato nella stessa regione in cui AWS CLI è stata creata l'applicazione di esempio Scorekeep.
Gli script incluso per testare l'applicazione di esempio utilizzano `cURL` per inviare il traffico verso l'API e `jq` per analizzare l'output. Puoi scaricare l'eseguibile di `jq` da [stedolan.github.io](https://stedolan.github.io/jq/) e l'eseguibile di `curl` da [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html). La maggior parte delle installazioni Linux e OS X include cURL.
## Generare i dati di tracciamento
Mentre il gioco è in corso, l'applicazione web genera continuamente traffico verso l'API ogni pochi secondi, ma genera solo un tipo di richiesta. Utilizza lo script `test-api.sh` per eseguire scenari completi e generare dati di tracciamento più eterogeni mentre testi l'API.
**Per usare lo script `test-api.sh`**
1. Apri la [console Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Accedi alla [console di gestione del](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) tuo ambiente.
1. Copiare l'**URL** di ambiente dall'intestazione della pagina.
1. Aprire `bin/test-api.sh` e sostituire il valore per l’API con l'URL del proprio ambiente.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. Eseguire lo script per generare il traffico verso 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"]}
```
## Usa l'API X-Ray
La AWS CLI fornisce comandi per tutte le azioni API fornite da X-Ray, tra cui e. [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) Per ulteriori informazioni su tutte le operazioni supportate e i tipi di dati che utilizzano, consulta la [Guida di riferimento delle API di AWS X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html).
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
Lo script recupera un grafo del servizio relativo agli ultimi 10 minuti.
```
~/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'
```
Lo script recupera le URLs tracce generate tra uno e due minuti fa.
```
~/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[*]'
```
Lo script recupera i tracciamenti completi generati tra uno e due minuti fa.
```
~/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
}
...
```
## Rimozione
Termina il tuo ambiente Elastic Beanstalk per chiudere le istanze EC2 Amazon, le tabelle DynamoDB e altre risorse.
**Per terminare l'ambiente Elastic Beanstalk**
1. Apri la [console Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. [Accedi alla console di gestione del tuo ambiente.](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)
1. Scegliere **Actions (Operazioni)**.
1. Scegliere **Terminate Environment (Termina ambiente)**.
1. Scegliere **Terminate (Termina)**.
I dati di traccia vengono eliminati automaticamente da X-Ray dopo 30 giorni.
# Invio di dati di tracciamento a AWS X-Ray
È possibile inviare dati di traccia a X-Ray sotto forma di documenti di segmento. Un documento di segmento è una stringa in formato JSON che contiene le informazioni sull'attività eseguita dalla tua applicazione per il soddisfacimento di una richiesta. La tua applicazione può memorizzare i dati sull'attività che svolge in segmenti, oppure le attività che utilizzano i servizi e le risorse a valle possono creare dei sottosegmenti.
I segmenti registrano le informazioni sull'attività svolta dalla tua applicazione. Un segmento registra almeno il tempo impiegato per un'attività, un nome e due IDs. L'ID di tracciamento monitora la richiesta durante il suo passaggio tra i servizi. L'ID segmento monitora l'attività svolta per la richiesta proveniente da uno specifico servizio.
**Example Segmento completo minimale**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Quando ricevi una richiesta, puoi inviare un segmento in esecuzione come segnaposto fino al completamento della richiesta.
**Example Segmento in esecuzione**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
È possibile inviare segmenti a X-Ray direttamente, [`PutTraceSegments`](#xray-api-segments)con [o tramite il demone X-Ray](#xray-api-daemon).
La maggior parte delle applicazioni richiama altri servizi o accede a risorse con l'SDK. AWS *Registra le informazioni sulle chiamate downstream in sottosegmenti.* X-Ray utilizza i sottosegmenti per identificare i servizi a valle che non inviano segmenti e creare le relative voci nel grafico dei servizi.
Un sottosegmento può essere incorporato in un documento di segmento completo oppure può essere inviato in modo separato. Invia i sottosegmenti separatamente per tracciare in modo asincrono le chiamate downstream per richieste di lunga durata o per evitare di superare la dimensione massima del documento del segmento (64 kB).
**Example Segmento secondario**
Un sottosegmento presenta un `type` valorizzato a `subsegment` e un `parent_id` che identifica il segmento padre.
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
Per ulteriori informazioni sui campi e i valori che puoi includere in segmenti e sottosegmenti, consulta [AWS X-Ray segmentare i documenti](xray-api-segmentdocuments.md).
**Topics**
+ [Generazione di tracce IDs](#xray-api-traceids)
+ [Usando PutTraceSegments](#xray-api-segments)
+ [Invio di documenti di segmento al demone X-Ray](#xray-api-daemon)
## Generazione di tracce IDs
Per inviare dati a X-Ray, è necessario generare un ID di traccia univoco per ogni richiesta.
**Formato ID di traccia X-Ray**
Una radiografia `trace_id` è composta da tre numeri separati da trattini. Ad esempio, `1-58406520-a006649127e371903a2de979`. Questo include:
+ Il numero di versione, che è. `1`
+ L'ora della richiesta originale in Unix epoch time utilizzando **8 cifre esadecimali**.
Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. `1480615200` `58406520`
+ **Un identificatore a 96 bit univoco a livello globale per la traccia in 24 cifre esadecimali.**
**Nota**
X-Ray ora supporta IDs le tracce create utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica [W3C](https://www.w3.org/TR/trace-context/) Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C `4efaaf4d1e8720b39541901950019ee5` deve essere formattato come `1-4efaaf4d-1e8720b39541901950019ee5` quando si invia a X-Ray. La traccia X-Ray IDs include il timestamp originale della richiesta in Unix epoch Time, ma questo non è necessario quando si invia la traccia W3C in formato X-Ray. IDs
È possibile scrivere uno script per generare una traccia a raggi X IDs per il test. Qui di seguito sono riportati due esempi.
**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"
```
Vedi l'applicazione di esempio Scorekeep per gli script che creano, tracciano IDs e inviano segmenti al demone 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)
## Usando PutTraceSegments
Puoi caricare i documenti di segmento tramite 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 dispone di un singolo parametro, `TraceSegmentDocuments`, che richiede un elenco di documenti di segmento in formato JSON.
Con l'AWS CLI, usa il `aws xray put-trace-segments` comando per inviare documenti di segmento direttamente a 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": []
}
```
**Nota**
Windows Command Processor e Windows PowerShell hanno requisiti diversi per la citazione e l'escape delle virgolette nelle stringhe JSON. Per i dettagli, consulta [Utilizzo delle virgolette nelle stringhe](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings) nella Guida per l'utente della AWS CLI .
L'output elenca tutti i segmenti per i quali l'elaborazione non è riuscita. Ad esempio, se la data nell'ID di tracciamento è troppo remota nel passato, verrà visualizzato un errore come il seguente.
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
Puoi passare più documenti di segmento insieme, separati da spazi.
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## Invio di documenti di segmento al demone X-Ray
Invece di inviare documenti di segmento all'API X-Ray, puoi inviare segmenti e sottosegmenti al daemon X-Ray, che li memorizzerà nel buffer e li caricherà sull'API X-Ray in batch. L'X-Ray SDK invia i documenti dei segmenti al demone per evitare di effettuare chiamate dirette. AWS
**Nota**
Per istruzioni sull'esecuzione del daemon, consulta [Esecuzione locale del demone X-Ray](xray-daemon-local.md).
Invia il segmento in formato JSON tramite la porta UDP 2000, anteponendo l'intestazione per il daemon, `{"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"}
```
Su Linux, puoi inviare documenti di segmento al daemon tramite un terminale Bash. Salva l'intestazione e il documento di segmento in un file di testo e reindirizzalo verso `/dev/udp` con `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"}
```
Controllate il [registro del demone](xray-daemon.md#xray-daemon-logging) per verificare che abbia inviato il segmento a 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)
```
# Ottenere dati da AWS X-Ray
AWS X-Ray elabora i dati di traccia che gli invii per generare tracce complete, riepiloghi di traccia e grafici di servizio in JSON. Puoi recuperare i dati generati direttamente dall'API con la AWS CLI.
**Topics**
+ [Recupero del grafico del servizio](#xray-api-servicegraph)
+ [Recupero del grafico del servizio dal gruppo](#xray-api-servicegraphgroup)
+ [Recupero dei tracciamenti](#xray-api-traces)
+ [Recupero e definizione dell’analisi delle cause principali](#xray-api-analytics)
## Recupero del grafico del servizio
Puoi utilizzare l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) per recuperare il grafico del servizio in formato JSON. L'API richiede un'ora di inizio e di fine, che puoi calcolare in un terminale Linux con il comando `date`.
```
$ date +%s
1499394617
```
`date +%s` converte una data in secondi. Utilizza questo numero come ora finale e sottrai da esso il tempo necessario per ottenere un'ora di inizio.
**Example Script per recuperare un grafico del servizio relativo agli ultimi 10 minuti**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
L'esempio seguente mostra un grafico di servizio con 4 nodi, tra cui un nodo client, un' EC2 istanza, una tabella DynamoDB e un argomento Amazon SNS.
**Example GetServiceGraph output**
```
{
"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
}
]
}
]
}
```
## Recupero del grafico del servizio dal gruppo
Per effettuare la chiamata a un grafico del servizio in base al contenuto di un gruppo, includi `groupName` o `groupARN`. L'esempio seguente mostra una chiamata del grafico del servizio a un gruppo denominato Example1.
**Example Script per recuperare un grafico del servizio in base al nome del gruppo Example1**
```
aws xray get-service-graph --group-name "Example1"
```
## Recupero dei tracciamenti
Puoi utilizzare l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) per ottenere un elenco di riepiloghi dei tracciamenti. I riepiloghi delle tracce includono informazioni che è possibile utilizzare per identificare le tracce che si desidera scaricare per intero, tra cui annotazioni, informazioni su richieste e risposte e. IDs
Ci sono due flag `TimeRangeType` disponibili quando si chiama `aws xray get-trace-summaries`:
+ **TraceId**— La `GetTraceSummaries` ricerca predefinita utilizza l'ora TraceID e restituisce le tracce iniziate all'interno dell'intervallo calcolato. `[start_time, end_time)` Questo intervallo di timestamp viene calcolato in base alla codifica del timestamp all'interno di o può essere definito manualmente. TraceId
+ **Ora dell'evento**: per cercare gli eventi man mano che si verificano nel tempo, AWS X-Ray consente di cercare le tracce utilizzando i timestamp degli eventi. L'ora dell'evento restituisce i tracciamenti attivi durante l'intervallo `[start_time, end_time)`, indipendentemente dall'inizio del tracciamento.
Utilizza il comando `aws xray get-trace-summaries` per ottenere un elenco di riepiloghi di tracciamento. I seguenti comandi ottengono un elenco di riepiloghi delle tracce relative a un periodo compreso tra 1 e 2 minuti nel passato utilizzando l'ora predefinita. TraceId
**Example Script per ottenere i riepiloghi dei tracciamenti**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries uscita**
```
{
"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
}
```
Utilizza l'ID di tracciamento nell'output per recuperare un tracciamento completo con 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 comando**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces uscita**
```
{
"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": []
}
```
Il tracciamento completo include un documento per ogni segmento, creato a partire da tutti i documenti di segmento con lo stesso ID di tracciamento ricevuti. Questi documenti non rappresentano i dati inviati a X-Ray dall'applicazione. Rappresentano invece i documenti elaborati generati dal servizio X-Ray. X-Ray crea il documento di traccia completo compilando i documenti dei segmenti inviati dall'applicazione e rimuovendo i dati che non sono conformi allo schema del documento del [segmento](xray-api-segmentdocuments.md).
X-Ray crea anche *segmenti dedotti per le* chiamate downstream verso servizi che non inviano segmenti di per sé. Ad esempio, quando si chiama DynamoDB con un client strumentato, l'SDK X-Ray registra un sottosegmento con dettagli sulla chiamata dal suo punto di vista. Tuttavia, DynamoDB non invia un segmento corrispondente. X-Ray utilizza le informazioni nel sottosegmento per creare un segmento dedotto per rappresentare la risorsa DynamoDB nella mappa di traccia e lo aggiunge al documento di traccia.
[Per ottenere più tracce dall'API, è necessario un elenco di tracce IDs, che è possibile estrarre dall'output di con una query. `get-trace-summaries`AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter) Reindirizza l'elenco all'input di `batch-get-traces` per ottenere tracce complete per un periodo di tempo specifico.
**Example Script per ottenere i tracciamenti completi per un periodo di un minuto**
```
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[*]'
```
## Recupero e definizione dell’analisi delle cause principali
Dopo aver generato un riepilogo delle tracce con l'[GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html), è possibile riutilizzare i riepiloghi delle tracce parziali nel formato JSON per creare un'espressione di filtro raffinata basata sulle cause principali. Consulta gli esempi riportati di seguito per una procedura guidata per le fasi di definizione.
**Example Esempio GetTraceSummaries di output: sezione relativa al tempo di risposta e alla causa principale**
```
{
"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
}
]
}
]
}
```
Modificando e apportando omissioni all'output precedente, questo JSON può diventare un filtro per le entità di cause principali corrispondenti. Per tutti i campi presenti nel JSON, ogni corrispondenza dei candidati deve essere esatta o il tracciamento non verrà restituito. I campi rimossi diventano valori jolly, un formato compatibile con la struttura di query dell’espressione di filtro.
**Example Causa principale del tempo di risposta riformattata**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
Questo JSON viene quindi utilizzato come parte di un'espressione di filtro tramite una chiamata a `rootcause.json = #[{}]`. Consulta il capitolo [Espressioni di filtro](xray-console-filters.md) per ulteriori dettagli sulle query con espressioni di filtro.
**Example Esempio di filtro JSON**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# Configurazione delle impostazioni di campionamento, gruppi e crittografia con l'API AWS X-Ray
AWS X-Ray [consente di configurare APIs le regole di [campionamento, le regole](xray-console-sampling.md) di gruppo e le impostazioni di crittografia.](xray-console-encryption.md)
**Topics**
+ [Impostazioni di crittografia](#xray-api-configuration-encryption)
+ [Regole di campionamento](#xray-api-configuration-sampling)
+ [Gruppi](#xray-api-configuration-groups)
## Impostazioni di crittografia
Si usa [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)per specificare una chiave AWS Key Management Service (AWS KMS) da usare per la crittografia.
**Nota**
X-Ray non supporta le chiavi KMS asimmetriche.
```
$ 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"
}
}
```
Come ID della chiave, puoi utilizzare un alias (come illustrato nell'esempio), una ID della chiave o di un ARN (Amazon Resource Name).
Utilizza [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) per recuperare la configurazione corrente. Quando X-Ray termina di applicare le impostazioni, lo stato cambia da a`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"
}
}
```
Per smettere di usare una chiave KMS e utilizzare la crittografia predefinita, imposta il tipo di crittografia su. `NONE`
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## Regole di campionamento
Puoi gestire le [regole di campionamento](xray-console-sampling.md) nel tuo account con l'API X-Ray. Per ulteriori informazioni sull'aggiunta e la gestione dei tag, consulta. [Etichettatura delle regole e dei gruppi di campionamento a raggi X](xray-tagging.md)
Recupera tutte le regole di campionamento utilizzando l'API [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
}
]
}
```
La regola di default si applica a tutte le richieste che non soddisfano nessun'altra regola. Si tratta della regola a priorità più bassa e non può essere eliminata. Puoi, tuttavia, modificare la percentuale e la dimensione della riserva utilizzando [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html).
**Example Input API per: [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'esempio seguente utilizza il file precedente come input per modificare la regola di default impostando una percentuale dell'1% senza riserva. I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi. Per rimuovere i tag esistenti da una regola di campionamento, usa [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
},
```
Crea regole di campionamento aggiuntive con [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html). Quando crei una regola, la maggior parte dei campi della regola sono obbligatori. L'esempio seguente crea due regole. Questa prima regola imposta una percentuale fissa per l'applicazione di esempio Scorekeep. Si applica a tutte le richieste elaborate dall'API alle quali non si applicano regole di priorità maggiore.
**Example Input API per: [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
}
}
```
Anche la seconda regola si applica a Scorekeep, ma le è assegnata una priorità maggiore ed è più specifica. Questa regola consente di impostare una percentuale di campionamento molto bassa per le richieste di polling. Queste sono le richieste GET effettuate dal client ogni pochi secondi per verificare la presenza di modifiche allo stato del gioco.
**Example Input API per [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
}
}
```
I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi.
```
$ 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
}
}
```
Per eliminare una regola di campionamento, utilizza [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
}
}
```
## Gruppi
Puoi utilizzare l'API X-Ray per gestire i gruppi nel tuo account. I gruppi costituiscono una raccolta di tracce definite da un'espressione di filtro. Puoi utilizzare i gruppi per generare grafici di servizio aggiuntivi e fornire CloudWatch metriche Amazon. Vedi [Ottenere dati da AWS X-Ray](xray-api-gettingdata.md) per maggiori dettagli sull'utilizzo dei grafici e delle metriche dei servizi tramite l'API X-Ray. Per ulteriori informazioni sui gruppi, vedere. [Configurazione dei gruppi](xray-console-groups.md) Per ulteriori informazioni sull'aggiunta e la gestione dei tag, vedere[Etichettatura delle regole e dei gruppi di campionamento a raggi X](xray-tagging.md).
Crea un gruppo con `CreateGroup`. I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi.
```
$ 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}"
}
```
Ottieni tutti i gruppi esistenti con `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"
}
```
Aggiorna un gruppo con `UpdateGroup`. I tag sono opzionali. Se scegli di aggiungere tag, è necessaria una chiave di tag e i valori dei tag sono facoltativi. Per rimuovere i tag esistenti da un gruppo, usa [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}"
}
```
Elimina un gruppo con `DeleteGroup`.
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# Using sampling rules with the X-Ray API (Utilizzo delle regole di campionamento con l'API X-Ray)
L' AWS X-Ray SDK utilizza l'API X-Ray per ottenere regole di campionamento, riportare i risultati del campionamento e ottenere quote. Puoi utilizzarli APIs per comprendere meglio come funzionano le regole di campionamento o per implementare il campionamento in un linguaggio non supportato da X-Ray SDK.
Inizia a recuperare tutte le regole di campionamento con [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
}
]
}
```
L'output include la regola di default e regole personalizzate. Se non hai ancora creato nessuna regola di campionamento, consulta [Regole di campionamento](xray-api-configuration.md#xray-api-configuration-sampling).
Valuta le regole rispetto alle richieste in entrata in ordine crescente di priorità. Quando una regola viene soddisfatta, utilizza la percentuale fissa e la dimensione della riserva per prendere una decisione sul campionamento. Registra le richieste campionate e ignora (ai fini del tracciamento) le richieste non campionate. Interrompe la valutazione delle regole nel momento un cui viene assunta una decisione sul campionamento.
La dimensione della riserva di una regola è il numero di tracciamenti al secondo da registrare prima di applicare la percentuale fissa. La riserva è conteggiata su tutti i servizi in modo cumulativo, quindi non puoi utilizzarla direttamente. Tuttavia, se è diverso da zero, è possibile prendere in prestito una traccia al secondo dal serbatoio fino a quando X-Ray non assegna una quota. Prima di ricevere una quota, registra la prima richiesta ogni secondo e applica la percentuale fissa per ulteriori richieste. La percentuale fissa è un numero decimale tra 0 e 1,00 (100%).
L'esempio seguente mostra una chiamata a [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) con dettagli sulle decisioni di campionamento effettuate negli ultimi 10 secondi.
```
$ 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 risposta di X-Ray include una quota da utilizzare invece di prendere in prestito dal serbatoio. In questo esempio, il servizio ha prelevato 10 tracciamenti dalla riserva durante i 10 secondi, e viene applicata la percentuale fissa del 10% per le altre 100 richieste, generando un totale di 20 richieste campionate. La quota è valida per cinque minuti (indicata dal periodo di vita) o fino all'assegnazione di una nuova quota. X-Ray può anche assegnare un intervallo di segnalazione più lungo di quello predefinito, anche se qui non è così.
**Nota**
La risposta di X-Ray potrebbe non includere una quota la prima volta che viene chiamata. Continua a prelevare dalla riserva finché non viene assegnata una quota.
Gli altri due campi della risposta possono indicare dei problemi con l'input. Controlla `LastRuleModification` rispetto all'ultima chiamata di [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html). Se è più recente, scarica una nuova copia delle regole. `UnprocessedStatistics` può includere errori che indicano che una regola è stata eliminata, che il documento delle statistiche di input era troppo vecchio o che sono presenti dei problemi con le autorizzazioni.
# AWS X-Ray segmentare i documenti
Un **segmento di tracciamento** è una rappresentazione JSON di una richiesta elaborata dalla tua applicazione. Un segmento di traccia registra informazioni sulla richiesta originale, informazioni sul lavoro svolto localmente dall'applicazione e **sottosegmenti** con informazioni sulle chiamate downstream effettuate dall'applicazione alle AWS risorse, ai database HTTP e SQL. APIs
Un **documento di segmento** trasmette informazioni su un segmento a X-Ray. Un documento di segmento può pesare fino a 64 kB e contenere un intero segmento con sottosegmenti, un frammento di segmento che indica che una richiesta è in corso o un singolo sottosegmento inviato separatamente. È possibile inviare documenti segmentati direttamente a X-Ray utilizzando 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 compila ed elabora i documenti dei segmenti per generare **riepiloghi delle tracce** interrogabili e **tracce complete** a cui è possibile accedere utilizzando rispettivamente il comando e. [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) APIs Oltre ai segmenti e ai sottosegmenti inviati a X-Ray, il servizio utilizza le informazioni nei sottosegmenti per generare segmenti **dedotti** e li aggiunge alla traccia completa. I segmenti dedotti rappresentano i servizi e le risorse a valle nella mappa di traccia.
X-Ray fornisce uno **schema JSON** per i documenti dei segmenti. [È possibile scaricare lo schema qui: xray-segmentdocument-schema-v 1.0.0.](samples/xray-segmentdocument-schema-v1.0.0.zip) I campi e gli oggetti elencati nello schema sono descritti in modo dettagliato nelle sezioni seguenti.
Un sottoinsieme di campi di segmento viene indicizzato da X-Ray per essere utilizzato con le espressioni di filtro. Ad esempio, se imposti il `user` campo su un segmento su un identificatore univoco, puoi cercare segmenti associati a utenti specifici nella console X-Ray o utilizzando l'API. `GetTraceSummaries` Per ulteriori informazioni, consulta [Utilizzo delle espressioni di filtro](xray-console-filters.md).
Quando strumentate la vostra applicazione con l'SDK X-Ray, l'SDK genera documenti di segmento per voi. [Invece di inviare i documenti segmentati direttamente a X-Ray, l'SDK li trasmette tramite una porta UDP locale al demone X-Ray.](xray-daemon.md) Per ulteriori informazioni, consulta [Invio di documenti di segmento al demone X-Ray](xray-api-sendingdata.md#xray-api-daemon).
**Topics**
+ [Campi del segmento](#api-segmentdocuments-fields)
+ [Sottosegmenti](#api-segmentdocuments-subsegments)
+ [Dati sulle richieste HTTP](#api-segmentdocuments-http)
+ [Annotazioni](#api-segmentdocuments-annotations)
+ [Metadati](#api-segmentdocuments-metadata)
+ [AWS dati relativi alle risorse](#api-segmentdocuments-aws)
+ [Errori ed eccezioni](#api-segmentdocuments-errors)
+ [Query SQL](#api-segmentdocuments-sql)
## Campi del segmento
Un segmento memorizza le informazioni di tracciamento relative a una richiesta elaborata dalla tua applicazione. Come minimo, un segmento memorizza nome, ID, ora di inizio, ID di tracciamento e ora di fine della richiesta.
**Example Segmento completo minimale**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Di seguito sono elencati i campi obbligatori, o condizionalmente obbligatori, per i segmenti.
**Nota**
I valori devono essere stringhe (lunghe fino a un massimo di 250 caratteri) a meno che non sia indicato altrimenti.
**Campi del segmento obbligatori**
+ `name`**— Il nome logico del servizio che ha gestito la richiesta, fino a 200 caratteri.** Ad esempio, il nome dell'applicazione o il nome di dominio. I nomi possono contenere lettere in formato Unicode, numeri e spazi e i seguenti simboli: `_`, `.`, `:`, `/`, `%`, `&`, `#`, `=`, `+`, `\`, `-`, `@`
+ `id`— Un identificatore a 64 bit per il segmento, unico tra i segmenti della stessa traccia, in **16** cifre esadecimali.
+ `trace_id`— Un identificatore univoco che collega tutti i segmenti e i sottosegmenti provenienti da una singola richiesta del client.
**Formato ID di traccia X-Ray**
Una radiografia `trace_id` è composta da tre numeri separati da trattini. Ad esempio `1-58406520-a006649127e371903a2de979`. Questo include:
+ Il numero di versione, che è. `1`
+ L'ora della richiesta originale in Unix epoch time utilizzando **8 cifre esadecimali**.
Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. `1480615200` `58406520`
+ **Un identificatore a 96 bit univoco a livello globale per la traccia in 24 cifre esadecimali.**
**Nota**
X-Ray ora supporta IDs le tracce create utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica [W3C](https://www.w3.org/TR/trace-context/) Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C `4efaaf4d1e8720b39541901950019ee5` deve essere formattato come `1-4efaaf4d-1e8720b39541901950019ee5` quando si invia a X-Ray. La traccia X-Ray IDs include il timestamp originale della richiesta in Unix epoch Time, ma questo non è necessario quando si invia la traccia W3C in formato X-Ray. IDs
**Sicurezza dell'ID di tracciamento**
[Le tracce sono visibili nelle intestazioni di risposta. IDs ](xray-concepts.md#xray-concepts-tracingheader) Genera tracce IDs con un algoritmo casuale sicuro per garantire che gli aggressori non possano calcolare le tracce future IDs e inviare richieste con quelle IDs alla tua applicazione.
+ `start_time`— **numero** che indica l'ora in cui il segmento è stato creato, in secondi a virgola mobile nell'ora dell'epoca. Ad esempio `1480615200.010` o `1.480615200010E9`. Utilizza il numero di cifre decimali di cui hai bisogno. Quando disponibile, è consigliata la risoluzione al microsecondo.
+ `end_time`— **numero** che indica l'ora in cui il segmento è stato chiuso. Ad esempio `1480615200.090` o `1.480615200090E9`. Specifica un `end_time` oppure il valore `in_progress`.
+ `in_progress`— **booleano**, impostato su `true` invece di specificare an `end_time` per registrare che un segmento è iniziato, ma non è completo. Invia la segnalazione di un segmento in elaborazione per memorizzare la richiesta ricevuta quando l'applicazione riceve una richiesta la cui esecuzione richiede molto tempo. Quando viene inviata la risposta, invia il completamento del segmento per sovrascrivere il segmento in elaborazione. Per ogni richiesta, invia un solo segmento completo e uno o nessun segmento in esecuzione.
**Nomi dei servizi**
I segmenti `name` devono corrispondere al nome di dominio o al nome logico del servizio che genera il segmento. Tuttavia, questo non viene applicato. Qualsiasi applicazione autorizzata [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)può inviare segmenti con qualsiasi nome.
I seguenti campi dei segmenti sono facoltativi.
**Campi del segmento facoltativi**
+ `service`— Un oggetto con informazioni sull'applicazione.
+ `version`— Una stringa che identifica la versione dell'applicazione che ha fornito la richiesta.
+ `user`— Una stringa che identifica l'utente che ha inviato la richiesta.
+ `origin`— Il tipo di AWS risorsa che esegue l'applicazione.
**Valori supportati**
+ `AWS::EC2::Instance`— Un' EC2 istanza Amazon.
+ `AWS::ECS::Container`— Un contenitore Amazon ECS.
+ `AWS::ElasticBeanstalk::Environment`— Un ambiente Elastic Beanstalk.
Quando, per la tua applicazione, sono validi più valori, utilizza quello più specifico. Ad esempio, un ambiente Docker Elastic Beanstalk Multicontainer esegue l'applicazione su un contenitore Amazon ECS, che a sua volta viene eseguito su un'istanza Amazon. EC2 In questo caso, è possibile impostare l'origine a `AWS::ElasticBeanstalk::Environment` poiché l'ambiente è il padre delle altre due risorse.
+ `parent_id`— Un ID di sottosegmento che specifichi se la richiesta proviene da un'applicazione strumentata. L'X-Ray SDK aggiunge l'ID del sottosegmento principale all'[intestazione di tracciamento per le chiamate HTTP downstream](xray-concepts.md#xray-concepts-tracingheader). Nel caso di sottosegmenti nidificati, un sottosegmento può avere come padre un segmento o un sottosegmento.
+ `http`— [`http`](#api-segmentdocuments-http)oggetti con informazioni sulla richiesta HTTP originale.
+ `aws`— [`aws`](#api-segmentdocuments-aws)oggetto con informazioni sulla AWS risorsa su cui l'applicazione ha fornito la richiesta.
+ `error`, `throttle``fault`, e `cause` — campi [di errore](#api-segmentdocuments-errors) che indicano che si è verificato un errore e che includono informazioni sull'eccezione che ha causato l'errore.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)oggetto con coppie chiave-valore che si desidera che X-Ray indicizzi per la ricerca.
+ `metadata`— [`metadata`](#api-segmentdocuments-metadata)oggetto con eventuali dati aggiuntivi che si desidera memorizzare nel segmento.
+ `subsegments`— **matrice** di [`subsegment`](#api-segmentdocuments-subsegments)oggetti.
## Sottosegmenti
È possibile creare sottosegmenti per registrare le chiamate Servizi AWS e le risorse effettuate con l' AWS SDK, le chiamate al Web APIs HTTP interno o esterno o le query del database SQL. Puoi anche creare dei sottosegmenti per eseguire il debug o annotare blocchi di codice dell'applicazione. I sottosegmenti possono contenere a loro volta altri sottosegmenti, perciò un sottosegmento personalizzato che memorizza i metadati su una chiamata ad una funzione interna può contenere altri sottosegmenti personalizzati o sottosegmenti relativi alle chiamate a valle.
Un sottosegmento registra una chiamata a valle dal punto di vista del servizio che la chiama. X-Ray utilizza i sottosegmenti per identificare i servizi a valle che non inviano segmenti e creare le relative voci nel grafico dei servizi.
Un sottosegmento può essere incorporato in un intero documento di segmento oppure può essere inviato in modo indipendente. Invia sottosegmenti separatamente per tracciare in modo asincrono le chiamate a valle in caso di richieste di lunga durata, oppure per evitare di superare la dimensione massima del documento di segmento.
**Example Segmento con sottosegmento incorporato**
Un sottosegmento indipendente presenta un `type` valorizzato a `subsegment` e un `parent_id` che identifica il segmento padre.
```
{
"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
}
}
}
]
}
```
Per le richieste di lunga durata, è possibile inviare un segmento in corso per notificare a X-Ray che la richiesta è stata ricevuta e quindi inviare i sottosegmenti separatamente per tracciarli prima di completare la richiesta originale.
**Example Segmento in esecuzione**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example Sottosegmento indipendente**
Un sottosegmento presenta un `type` valorizzato a `subsegment`, un `trace_id` e un `parent_id` che identifica il segmento padre.
```
{
"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
}
}
}
```
Quando la richiesta viene completata, chiudi il segmento inviandolo nuovamente con il campo `end_time` valorizzato. Il segmento completato sovrascrive il segmento in elaborazione.
Puoi anche inviare i sottosegmenti separatamente per richieste completate che hanno attivato flussi di lavoro asincroni. Ad esempio, un'API web potrebbe restituire immediatamente una risposta `OK 200` prima di avviare l'attività richiesta dall'utente. È possibile inviare un segmento completo a X-Ray non appena viene inviata la risposta, seguito da sottosegmenti per il lavoro completato in un secondo momento. Come nel caso dei segmenti, puoi anche inviare un sottosegmento per memorizzare l'inizio del sottosegmento stesso e quindi sovrascriverlo con un sottosegmento completo una volta completata la chiamata a valle.
Di seguito sono elencati i campi obbligatori, o condizionalmente obbligatori, per i sottosegmenti.
**Nota**
I valori devono essere stringhe lunghe fino a un massimo di 250 caratteri, a meno che non sia indicato altrimenti.
**Campi del sottosegmento obbligatori**
+ `id`**— Un identificatore a 64 bit per il sottosegmento, unico tra i segmenti della stessa traccia, in 16 cifre esadecimali.**
+ `name`— Il nome logico del sottosegmento. Nel caso di chiamate a valle, denominare il sottosegmento in base alla risorsa o al servizio chiamati. Nel caso di sottosegmenti personalizzati, denominare il sottosegmento in base al codice che viene analizzato (ad esempio utilizzando un nome di funzione).
+ `start_time`— **numero** che indica l'ora in cui è stato creato il sottosegmento, in secondi a virgola mobile in base all'ora dell'epoca, preciso in millisecondi. Ad esempio `1480615200.010` o `1.480615200010E9`.
+ `end_time`— **numero** che indica l'ora in cui il sottosegmento è stato chiuso. Ad esempio `1480615200.090` o `1.480615200090E9`. Specificare un `end_time` o il valore `in_progress`.
+ `in_progress`— valore **booleano** impostato su `true` anziché specificare an per `end_time` registrare che un sottosegmento è iniziato, ma non è completo. Per ogni richiesta a valle, invia un solo sottosegmento completo e uno o nessun sottosegmento in lavorazione.
+ `trace_id`— ID di traccia del segmento principale del sottosegmento. Obbligatorio solo nel caso in cui si invii un sottosegmento in modo separato.
**Formato ID di traccia X-Ray**
Una radiografia `trace_id` è composta da tre numeri separati da trattini. Ad esempio `1-58406520-a006649127e371903a2de979`. Questo include:
+ Il numero di versione, che è. `1`
+ L'ora della richiesta originale in Unix epoch time utilizzando **8 cifre esadecimali**.
Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. `1480615200` `58406520`
+ **Un identificatore a 96 bit univoco a livello globale per la traccia in 24 cifre esadecimali.**
**Nota**
X-Ray ora supporta IDs le tracce create utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica [W3C](https://www.w3.org/TR/trace-context/) Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C `4efaaf4d1e8720b39541901950019ee5` deve essere formattato come `1-4efaaf4d-1e8720b39541901950019ee5` quando si invia a X-Ray. La traccia X-Ray IDs include il timestamp originale della richiesta in Unix epoch Time, ma questo non è necessario quando si invia la traccia W3C in formato X-Ray. IDs
+ `parent_id`— ID del segmento principale del sottosegmento. Obbligatorio solo nel caso in cui si invii un sottosegmento in modo separato. Nel caso di sottosegmenti nidificati, un sottosegmento può avere come padre un segmento o un sottosegmento.
+ `type`—`subsegment`. Richiesto solo se si invia un sottosegmento separatamente.
I seguenti campi dei sottosegmenti sono facoltativi.
**Campi del sottosegmento facoltativi**
+ `namespace`— `aws` per le chiamate SDK AWS; `remote` per altre chiamate downstream.
+ `http`— [`http`](#api-segmentdocuments-http)oggetto con informazioni su una chiamata HTTP in uscita.
+ `aws`— [`aws`](#api-segmentdocuments-aws)oggetto con informazioni sulla AWS risorsa downstream chiamata dall'applicazione.
+ `error`, `throttle``fault`, e `cause` — campi di [errore](#api-segmentdocuments-errors) che indicano che si è verificato un errore e che includono informazioni sull'eccezione che ha causato l'errore.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)oggetto con coppie chiave-valore che si desidera che X-Ray indicizzi per la ricerca.
+ `metadata`— [`metadata`](#api-segmentdocuments-metadata)oggetto con eventuali dati aggiuntivi che si desidera memorizzare nel segmento.
+ `subsegments`— **matrice** di [`subsegment`](#api-segmentdocuments-subsegments)oggetti.
+ `precursor_ids`— **matrice** di sottosegmenti IDs che identifica i sottosegmenti con lo stesso elemento principale completati prima di questo sottosegmento.
## Dati sulle richieste HTTP
Utilizza un blocco HTTP per memorizzare i dettagli relativi a una richiesta HTTP che la tua applicazione ha elaborato (in un segmento) oppure che la tua applicazione ha eseguito a valle verso un'API HTTP (in un sottosegmento). La maggior parte dei campi di questo oggetto corrispondono alle informazioni di una richiesta HTTP e della relativa risposta.
**`http`**
Tutti i campi sono facoltativi.
+ `request`— Informazioni su una richiesta.
+ `method`— Il metodo di richiesta. Ad esempio `GET`.
+ `url`— L'URL completo della richiesta, compilato a partire dal protocollo, dal nome host e dal percorso della richiesta.
+ `user_agent`— La stringa dell'agente utente proveniente dal client del richiedente.
+ `client_ip`— L'indirizzo IP del richiedente. Può essere recuperato dal campo `Source Address` del pacchetto IP o, in caso di richieste inoltrate, da un'intestazione `X-Forwarded-For`.
+ `x_forwarded_for`— (solo segmenti) **booleano** che indica che `client_ip` è stato letto da un'`X-Forwarded-For`intestazione e non è affidabile in quanto avrebbe potuto essere falsificato.
+ `traced`— (solo sottosegmenti) **booleano** che indica che la chiamata a valle è verso un altro servizio tracciato. Se questo campo è impostato su`true`, X-Ray considera la traccia interrotta finché il servizio downstream non carica un segmento con a `parent_id` che corrisponde al sottosegmento che `id` contiene questo blocco.
+ `response`— Informazioni su una risposta.
+ `status`— **numero intero** che indica lo stato HTTP della risposta.
+ `content_length`— **numero intero** che indica la lunghezza del corpo della risposta in byte.
Quando effettui una chiamata a un'API Web a valle, registra un sottosegmento con informazioni sulla richiesta e sulla risposta HTTP. X-Ray utilizza il sottosegmento per generare un segmento dedotto per l'API remota.
**Example Segmento per la chiamata HTTP servito da un'applicazione in esecuzione su 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 Sottosegmento per una chiamata HTTP a valle**
```
{
"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 Segmento dedotto per una chiamata HTTP a valle**
```
{
"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
}
```
## Annotazioni
I segmenti e i sottosegmenti possono includere un `annotations` oggetto contenente uno o più campi indicizzati da X-Ray per l'uso con le espressioni di filtro. I campi possono avere valori di tipo stringa, numerico o booleano (senza oggetti o matrici). X-Ray indica fino a 50 annotazioni per traccia.
**Example Segmento per chiamata HTTP con annotazioni**
```
{
"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
}
}
```
Per funzionare con i filtri, le chiavi devono essere di tipo alfanumerico. Il trattino basso è ammesso. Altri simboli e gli spazi non sono ammessi.
## Metadati
I segmenti e i sottosegmenti possono includere un `metadata` oggetto contenente uno o più campi con valori di qualsiasi tipo, inclusi oggetti e matrici. X-Ray non indicizza i metadati e i valori possono avere qualsiasi dimensione, purché il documento del segmento non superi la dimensione massima (64 kB). Puoi visualizzare i metadati nel documento di segmento completo restituito dall'API [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html). Le chiavi di campo (`debug`nell'esempio seguente) che iniziano con `AWS.` sono riservate all'uso da AWS-provided e dai client SDKs .
**Example Sottosegmento personalizzato con metadati**
```
{
"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 dati relativi alle risorse
Nel caso dei segmenti, l'oggetto `aws` contiene informazioni sulla risorsa su cui è in esecuzione l'applicazione. A una singola risorsa possono essere associati molteplici campi. Ad esempio, un'applicazione in esecuzione in un ambiente Docker multicontainer su Elastic Beanstalk potrebbe contenere informazioni sull'istanza Amazon, sul contenitore Amazon ECS in esecuzione sull' EC2 istanza e sull'ambiente Elastic Beanstalk stesso.
**`aws` (Segmenti)**
Tutti i campi sono facoltativi.
+ `account_id`— Se l'applicazione invia segmenti a un altro, registra l'ID dell'account su cui è in esecuzione l'applicazione. Account AWS
+ `cloudwatch_logs`— Matrice di oggetti che descrivono un singolo gruppo di CloudWatch log.
+ `log_group`— Il nome del gruppo di CloudWatch log.
+ `arn`— L' CloudWatch ARN del gruppo Log.
+ `ec2`— Informazioni su un' EC2 istanza Amazon.
+ `instance_id`— L'ID dell' EC2 istanza.
+ `instance_size`— Il tipo di EC2 istanza.
+ `ami_id`— L'Amazon Machine Image ID.
+ `availability_zone`— La zona di disponibilità in cui è in esecuzione l'istanza.
+ `ecs`— Informazioni su un container Amazon ECS.
+ `container`— Il nome host del contenitore.
+ `container_id`— L'ID completo del contenitore.
+ `container_arn`— L'ARN dell'istanza del contenitore.
+ `eks`— Informazioni su un cluster Amazon EKS.
+ `pod`— Il nome host del tuo pod EKS.
+ `cluster_name`— Il nome del cluster EKS.
+ `container_id`— L'ID completo del contenitore.
+ `elastic_beanstalk`— Informazioni su un ambiente Elastic Beanstalk. Puoi trovare queste informazioni in un file denominato `/var/elasticbeanstalk/xray/environment.conf` sulle più recenti piattaforme Elastic Beanstalk.
+ `environment_name`: il nome dell'ambiente.
+ `version_label`— Il nome della versione dell'applicazione attualmente distribuita sull'istanza che ha fornito la richiesta.
+ `deployment_id`— **numero** che indica l'ID dell'ultima distribuzione riuscita nell'istanza che ha fornito la richiesta.
+ `xray`— Metadati relativi al tipo e alla versione della strumentazione utilizzata.
+ `auto_instrumentation`— Booleano che indica se è stata utilizzata la strumentazione automatica (ad esempio, l'agente Java).
+ `sdk_version`— La versione dell'SDK o dell'agente in uso.
+ `sdk`— Il tipo di SDK.
**Example AWS blocco con plugin**
```
"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"
}
}
```
Per i sottosegmenti, registra le informazioni sulle risorse Servizi AWS e sulle risorse a cui l'applicazione accede. X-Ray utilizza queste informazioni per creare segmenti dedotti che rappresentano i servizi a valle nella mappa dei servizi.
**`aws` (Sottosegmenti)**
Tutti i campi sono facoltativi.
+ `operation`— Il nome dell'azione API richiamata contro una risorsa or. Servizio AWS
+ `account_id`— Se l'applicazione accede alle risorse di un account diverso o invia segmenti a un account diverso, registra l'ID dell'account proprietario della AWS risorsa a cui l'applicazione ha avuto accesso.
+ `region`— Se la risorsa si trova in una regione diversa dall'applicazione, registra la regione. Ad esempio `us-west-2`.
+ `request_id`— Identificatore univoco per la richiesta.
+ `queue_url`— Per le operazioni su una coda Amazon SQS, l'URL della coda.
+ `table_name`— Per le operazioni su una tabella DynamoDB, il nome della tabella.
**Example Sottosegmento per una chiamata a DynamoDB per salvare un elemento**
```
{
"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",
}
}
```
## Errori ed eccezioni
Quando si verifica un errore, puoi memorizzare le informazioni relative all'errore e le eccezioni generate. Memorizza gli errori nei segmenti quando l'applicazione restituisce un errore all'utente, e nei sottosegmenti quando l'errore è restituito da una chiamata a valle.
**tipi di errore**
Imposta uno o più dei seguenti campi a `true` per indicare che si è verificato un errore. In caso di errori composti è possibile associare molteplici tipi. Ad esempio, un errore `429 Too Many Requests` da una chiamata a valle può far sì che la tua applicazione ritorni un errore `500 Internal Server Error`, nel qual caso possono essere associati tutti e tre i tipi di errore.
+ `error`— **booleano** che indica che si è verificato un errore del client (il codice di stato della risposta era 4XX Client Error).
+ `throttle`*— **booleano** che indica che una richiesta è stata limitata (il codice di stato della risposta era 429 Too Many Requests).*
+ `fault`— **booleano** che indica che si è verificato un errore del server (il codice di stato della risposta era 5XX Server Error).
Indica la causa dell'errore includendo un oggetto **cause** nel segmento o nel sottosegmento.
**`cause`**
A causa può essere un ID di eccezione lungo **16 caratteri** o un oggetto con i campi riportati qui di seguito:
+ `working_directory`— Il percorso completo della directory di lavoro quando si è verificata l'eccezione.
+ `paths`— L'**array** di percorsi alle librerie o ai moduli in uso quando si è verificata l'eccezione.
+ `exceptions`— La **matrice** di oggetti di **eccezione**.
Includi informazioni dettagliate sull'errore in uno o più oggetti **exception**.
**`exception`**
Tutti i campi sono facoltativi.
+ `id`— Un identificatore a 64 bit per l'eccezione, unico tra i segmenti della stessa traccia, in **16 cifre esadecimali**.
+ `message`— Il messaggio di eccezione.
+ `type`— Il tipo di eccezione.
+ `remote`— **booleano** che indica che l'eccezione è stata causata da un errore restituito da un servizio a valle.
+ `truncated`— **numero intero** che indica il numero di stack frame omessi da. `stack`
+ `skipped`— numero **intero** che indica il numero di eccezioni che sono state saltate tra questa eccezione e la relativa eccezione figlia, ovvero l'eccezione che ha causato.
+ `cause`— ID dell'eccezione principale dell'eccezione, ovvero l'eccezione che ha causato l'eccezione.
+ `stack`— **matrice** di oggetti **StackFrame**.
Se disponibili, memorizza le informazioni sullo stack delle chiamate negli oggetti **stackFrame**.
**`stackFrame`**
Tutti i campi sono facoltativi.
+ `path`— Il percorso relativo al file.
+ `line`— La riga nel file.
+ `label`— Il nome della funzione o del metodo.
## Query SQL
Puoi creare o sottosegmenti per le query che la tua applicazione esegue su un database SQL.
**`sql`**
Tutti i campi sono facoltativi.
+ `connection_string`— Per SQL Server o altre connessioni al database che non utilizzano stringhe di connessione URL, registrare la stringa di connessione, escluse le password.
+ `url`— Per una connessione al database che utilizza una stringa di connessione URL, registrare l'URL, escluse le password.
+ `sanitized_query`— L'interrogazione del database, con tutti i valori forniti dall'utente rimossi o sostituiti da un segnaposto.
+ `database_type`— Il nome del motore del database.
+ `database_version`— Il numero di versione del motore di database.
+ `driver_version`— Il nome e il numero di versione del driver del motore di database utilizzato dall'applicazione.
+ `user`— Il nome utente del database.
+ `preparation`— `call` se la query utilizzava un`PreparedCall`; `statement` se l'interrogazione utilizzava un`PreparedStatement`.
**Example Sottosegmento con una query 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=?;"
}
}
```