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à.
# 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=?;"
}
}
```