本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS X-Ray 區段文件
**追蹤區段**是您應用程式所處理請求的 JSON 表示。追蹤區段會記錄原始請求的相關資訊、應用程式在本機執行之工作的相關資訊，以及包含應用程式對 AWS 資源、HTTP APIs 和 SQL 資料庫進行下游呼叫相關資訊的**子區段**。
**區段文件**會將區段的相關資訊傳遞給 X-Ray。區段文件最多可達 64 kB，並包含具有子區段的整個區段、表示請求正在進行中的區段片段，或個別傳送的單一子區段。您可以使用 [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。
X-Ray 會編譯和處理區段文件，以產生可查詢的**追蹤摘要**和**完整追蹤**，您可以分別使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)和 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) APIs 存取。除了您傳送至 X-Ray 的區段和子區段之外，服務也會使用子區段中的資訊來產生**推斷區段**，並將其新增至完整追蹤。推斷區段代表追蹤地圖中的下游服務和資源。
X-Ray 提供**區段文件的 JSON 結構描述**。您可以在此處下載結構描述：[xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip)。以下章節會更詳細的說明結構描述中所列出的欄位和物件。
區段欄位的子集由 X-Ray 編製索引，以便與篩選條件表達式搭配使用。例如，如果您將區段上的 `user` 欄位設定為唯一識別符，您可以在 X-Ray 主控台中或使用 `GetTraceSummaries` API 搜尋與特定使用者相關聯的區段。如需詳細資訊，請參閱[使用篩選條件表達式](xray-console-filters.md)。
當您使用 X-Ray 開發套件檢測應用程式時，開發套件會為您產生區段文件。SDK 不會直接將區段文件傳送到 X-Ray，而是透過本機 UDP 連接埠將文件傳輸至 [X-Ray 協助程式](xray-daemon.md)。如需詳細資訊，請參閱[將區段文件傳送至 X-Ray 協助程式](xray-api-sendingdata.md#xray-api-daemon)。
**Topics**
+ [區段欄位](#api-segmentdocuments-fields)
+ [子區段](#api-segmentdocuments-subsegments)
+ [HTTP 請求資料](#api-segmentdocuments-http)
+ [註釋](#api-segmentdocuments-annotations)
+ [中繼資料](#api-segmentdocuments-metadata)
+ [AWS 資源資料](#api-segmentdocuments-aws)
+ [錯誤和例外狀況](#api-segmentdocuments-errors)
+ [SQL 查詢](#api-segmentdocuments-sql)
## 區段欄位
區段會記錄您應用程式所處理請求的相關追蹤資訊。區段最少會記錄請求的名稱、ID、開始時間、追蹤 ID 及結束時間。
**Example 最小的完成區段**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
以下欄位為區段的必要項目或條件式必要項目。
**注意**
除非另有說明，否則值必須為字串 (最多 250 個字元)。
**必要的區段欄位**
+ `name` – 處理請求的服務邏輯名稱，最多 **200 個字元**。例如，您應用程式的名稱或網域名稱。名稱可包含 Unicode 字母、數字、空格和下列符號：`_`、`.`、`:`、`/`、`%`、`&`、`#`、`=`、`+`、`\`、`-`、`@`
+ `id` – 區段的 64 位元識別符，在相同追蹤中的區段中是唯一的，以 **16 個十六進位數字**表示。
+ `trace_id` – 唯一識別符，可連接來自單一用戶端請求的所有區段和子區段。
**X-Ray 追蹤 ID 格式**
X-Ray `trace_id`由以連字號分隔的三個數字組成。例如：`1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。
例如，10：00AM 2016 年 12 月 1 日 PST 以 epoch `58406520` 為單位是`1480615200`秒或十六進位數字。
+ 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字**表示。
**注意**
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。W3C 追蹤 ID 在傳送至 X-Ray 時，必須以 X-Ray 追蹤 ID 格式格式化。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要。
**追蹤 ID 安全**
您可在[回應標頭](xray-concepts.md#xray-concepts-tracingheader)中取得追蹤 ID。使用安全的隨機演算法產生追蹤 ID，以確保攻擊者無法計算未來的追蹤 ID，並使用這些 ID 傳送請求到您的應用程式。
+ `start_time` – 區段建立時間的**數字**，以 epoch 時間的浮點秒為單位。例如 `1480615200.010` 或 `1.480615200010E9`。視需要使用任意小數位數。建議盡可能使用毫秒解析度。
+ `end_time` – 區段關閉時間的**數字**。例如 `1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` – **布林值**，設定為 ，`true`而不是指定 `end_time`來記錄區段已啟動，但未完成。應用程式收到的請求需要很長時間時，請傳送進行中區段，以追蹤請求的接收情況。回應已傳送時，請傳送完成區段以覆寫進行中的區段。針對每個請求，請只傳送一個完成區段，以及一或零個進行中區段。
**服務名稱**
區段的 `name`應與產生區段之服務的網域名稱或邏輯名稱相符。不過，這不會強制執行。具有 許可的任何應用程式[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)都可以使用任何名稱傳送客群。
以下欄位是區段的選擇性欄位。
**選擇性區段欄位**
+ `service` – 包含應用程式相關資訊的物件。
+ `version` – 識別提供請求之應用程式版本的字串。
+ `user` – 識別傳送請求之使用者的字串。
+ `origin` – 執行您應用程式 AWS 的資源類型。
**支援值**
+ `AWS::EC2::Instance` – Amazon EC2 執行個體。
+ `AWS::ECS::Container` – Amazon ECS 容器。
+ `AWS::ElasticBeanstalk::Environment` – Elastic Beanstalk 環境。
當有多個值適用您的應用程式時，請使用最具指定性的。例如，多容器 Docker Elastic Beanstalk 環境會在 Amazon ECS 容器上執行您的應用程式，而該容器又會在 Amazon EC2 執行個體上執行。在此案例中，您會將來源設為 `AWS::ElasticBeanstalk::Environment`，因為環境是其他兩個資源的父系。
+ `parent_id` – 您指定的子區段 ID，如果請求來自經檢測的應用程式。X-Ray SDK 會將父子區段 ID 新增至下游 HTTP 呼叫的[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。
+ `http` – [`http`](#api-segmentdocuments-http) 物件，其中包含原始 HTTP 請求的相關資訊。
+ `aws` – [`aws`](#api-segmentdocuments-aws) 物件，其中包含應用程式提供請求之 AWS 資源的相關資訊。
+ `error`、`fault`、 `throttle`和 `cause` – 錯誤[錯誤和例外狀況](#api-segmentdocuments-errors)欄位，指出發生錯誤，並包含導致錯誤的例外狀況相關資訊。
+ `annotations` – 具有索引鍵/值對的[`annotations`](#api-segmentdocuments-annotations)物件，您希望 X-Ray 為搜尋編製索引。
+ `metadata` – [`metadata`](#api-segmentdocuments-metadata) 物件，其中包含您要存放在區段的任何其他資料。
+ `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments) 物件**陣列**。
## 子區段
您可以建立子區段來記錄對 的呼叫 AWS 服務 ，以及您使用 AWS SDK 進行的資源、對內部或外部 HTTP Web APIs呼叫，或 SQL 資料庫查詢。您也可以建立子區段，除錯或標註您應用程式中的程式碼區塊。子區段可包含其他子區段，因此記錄內部函數呼叫中繼資料的自訂子區段可包含其他自訂子區段及下游呼叫的子區段。
子區段會從呼叫它的服務觀點記錄下游呼叫。X-Ray 使用子區段來識別未傳送區段的下游服務，並在服務圖表上為其建立項目。
子區段可內嵌在完整區段文件中，或是分別傳送。將子區段分別傳送，來非同步追蹤長時間執行請求的下游呼叫，或是避免超過區段文件大小上限。
**Example 具有內嵌子區段的區段**
獨立子區段具備 `subsegment` 的 `type`，以及可識別父區段的 `parent_id`。
```
{
"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
}
}
}
]
}
```
對於長時間執行的請求，您可以傳送進行中區段以通知 X-Ray 已收到請求，然後單獨傳送子區段以追蹤它們，然後再完成原始請求。
**Example 進行中的區段**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 獨立子區段**
獨立子區段具備 `subsegment` 的 `type`、`trace_id` 及 `parent_id`，可識別父區段。
```
{
"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
}
}
}
```
當請求完成時，透過使用 `end_time` 重新傳送它來關閉區段。完整區段會覆寫正在進行中的區段。
您也可以為觸發非同步工作流程的已完成請求分別傳送子區段。例如，web API 可能會在開始使用者請求的工作前立即傳回 `OK 200` 回應。您可以在傳送回應後立即將完整區段傳送至 X-Ray，接著再將子區段傳送至稍後完成的工作。與區段相同，您也可以傳送子區段片段來記錄子區段已啟動，然後在完成下游呼叫時使用完整的子區段覆寫它。
以下欄位為子區段的必要項目或條件式必要項目。
**注意**
除非另有說明，否則值必須為字串 (最多 250 個字元)。
**必要的子區段欄位**
+ `id` – 子區段的 64 位元識別符，在相同追蹤中的區段中是唯一的，以 **16 十六進位數字**表示。
+ `name` – 子區段的邏輯名稱。針對下游呼叫，請在呼叫資源或服務後命名子區段。針對自訂子區段，請在其檢測的程式碼 (例如函數名稱) 之後命名子區段。
+ `start_time` – 子區段建立時間的**數字**，以 epoch 時間的浮點秒為單位，精確到毫秒。例如 `1480615200.010` 或 `1.480615200010E9`。
+ `end_time` – 子區段關閉時間的**數字**。例如 `1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` – 設定為 `true`而非指定 的**布林值**`end_time`，以記錄子區段已啟動，但尚未完成。針對每個下游請求，請只傳送一個完成子區段，以及一或零個進行中子區段。
+ `trace_id` – 子區段父區段的追蹤 ID。僅在分別傳送子區段時才為必要項目。
**X-Ray 追蹤 ID 格式**
X-Ray `trace_id`由以連字號分隔的三個數字組成。例如：`1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。
例如，10：00AM 2016 年 12 月 1 日 PST 以 epoch `58406520` 為單位是`1480615200`秒或十六進位數字。
+ 追蹤的全域唯一 96 位元識別符，以 **24 十六進位數字**表示。
**注意**
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。W3C 追蹤 ID 在傳送至 X-Ray 時，必須以 X-Ray 追蹤 ID 格式格式化。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要。
+ `parent_id` – 子區段父區段的區段 ID。僅在分別傳送子區段時才為必要項目。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。
+ `type` – `subsegment`。 只有在單獨傳送子區段時才需要。
以下欄位是子區段的選擇性欄位。
**選擇性子區段欄位**
+ `namespace` – `aws`用於 AWS 開發套件呼叫； `remote` 用於其他下游呼叫。
+ `http` – [`http`](#api-segmentdocuments-http) 物件，其中包含傳出 HTTP 呼叫的相關資訊。
+ `aws` – [`aws`](#api-segmentdocuments-aws) 物件，其中包含您應用程式呼叫的下游 AWS 資源相關資訊。
+ `error`、`fault`、 `throttle`和 `cause` – 錯誤[錯誤和例外狀況](#api-segmentdocuments-errors)欄位，指出發生錯誤，並包含導致錯誤的例外狀況相關資訊。
+ `annotations` – 具有索引鍵/值對的[`annotations`](#api-segmentdocuments-annotations)物件，您希望 X-Ray 為搜尋編製索引。
+ `metadata` – [`metadata`](#api-segmentdocuments-metadata) 物件，其中包含您要存放在區段的任何其他資料。
+ `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments) 物件**陣列**。
+ `precursor_ids` – 子區段 IDs**陣列**，可識別具有在此子區段之前完成之相同父系的子區段。
## HTTP 請求資料
使用 HTTP 區塊來記錄您應用程式所處理的 HTTP 請求相關詳細資訊 (位於區段中)，或是您應用程式對下游 HTTP API 所發出請求的相關詳細資訊 (位於子區段中)。此物件中大部分的欄位都會映射到 HTTP 請求和回應中找到的資訊。
**`http`**
所有欄位都是選擇性的。
+ `request` – 請求的相關資訊。
+ `method` – 請求方法。例如：`GET`。
+ `url` – 請求的完整 URL，從請求的通訊協定、主機名稱和路徑編譯。
+ `user_agent` – 來自請求者用戶端的使用者代理程式字串。
+ `client_ip` – 申請者的 IP 地址。可從 IP 封包的 `Source Address` 擷取，或是針對轉送的請求，則從 `X-Forwarded-For` 標頭擷取。
+ `x_forwarded_for` – （僅限區段） **布林值**，指出 `client_ip`是從 `X-Forwarded-For`標頭讀取，而且不可靠，因為它可能是偽造的。
+ `traced` – （僅限子區段） **布林值**，表示下游呼叫是對另一個追蹤服務。如果此欄位設定為 `true`，X-Ray 會將追蹤視為中斷，直到下游服務上傳的區段`parent_id`與包含此區塊之子區段`id`的 相符。
+ `response` – 回應的相關資訊。
+ `status` – **整數**，指出回應的 HTTP 狀態。
+ `content_length` – **整數**，表示回應內文的長度，以位元組為單位。
當您檢測對下游 Web api 的呼叫時，請記錄包含 HTTP 請求和回應相關資訊的子區段。X-Ray 使用 子區段來產生遠端 API 的推斷區段。
**Example 在 Amazon EC2 上執行之應用程式提供的 HTTP 呼叫區段**
```
{
"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 下游 HTTP 呼叫的子區段**
```
{
"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 下游 HTTP 呼叫的推斷區段**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
## 註釋
區段和子區段可以包含`annotations`物件，其中包含一或多個欄位，X-Ray 索引可與篩選條件表達式搭配使用。欄位可以有字串、數字或布林值 （無物件或陣列）。X-Ray 為每個追蹤編製最多 50 個註釋的索引。
**Example HTTP 呼叫區段與標註**
```
{
"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
}
}
```
鍵必須為英數字元，才能使用篩選條件。允許使用底線。不允許使用其他符號和空格。
## 中繼資料
區段和子區段可以包含`metadata`物件，其中包含一或多個具有任何類型值的欄位，包括物件和陣列。只要區段文件不超過大小上限 (64 kB)，X-Ray 不會為中繼資料編製索引，且值可以是任何大小。您可以在 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 傳回的完整區段文件中檢視中繼資料。以 開頭的欄位金鑰 (`debug`在下列範例中） `AWS.` 會保留供 提供的 SDKs AWS和用戶端使用。
**Example 使用中繼資料的自訂子區段**
```
{
"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 資源資料
針對區段，`aws` 物件包含您應用程式於其上執行的資源相關資訊。可將多個欄位套用至單一資源。例如，在 Elastic Beanstalk 上的多容器 Docker 環境中執行的應用程式，可能具有有關 Amazon EC2 執行個體、在執行個體上執行的 Amazon ECS 容器，以及 Elastic Beanstalk 環境本身的資訊。
**`aws` (區段)**
所有欄位都是選擇性的。
+ `account_id` – 如果您的應用程式將客群傳送到不同的 AWS 帳戶，請記錄執行您應用程式的 帳戶 ID。
+ `cloudwatch_logs` – 描述單一 CloudWatch 日誌群組的物件陣列。
+ `log_group` – CloudWatch Log Group 名稱。
+ `arn` – CloudWatch Log Group ARN。
+ `ec2` – Amazon EC2 執行個體的相關資訊。
+ `instance_id` – EC2 執行個體的執行個體 ID。
+ `instance_size` – EC2 執行個體的類型。
+ `ami_id` – Amazon Machine Image ID。
+ `availability_zone` – 執行個體執行所在的可用區域。
+ `ecs` – Amazon ECS 容器的相關資訊。
+ `container` – 容器的主機名稱。
+ `container_id` – 容器的完整容器 ID。
+ `container_arn` – 容器執行個體的 ARN。
+ `eks` – Amazon EKS 叢集的相關資訊。
+ `pod` – EKS Pod 的主機名稱。
+ `cluster_name` – EKS 叢集名稱。
+ `container_id` – 容器的完整容器 ID。
+ `elastic_beanstalk` – Elastic Beanstalk 環境的相關資訊。您可以在最新 Elastic Beanstalk 平台上名為 `/var/elasticbeanstalk/xray/environment.conf`的檔案中找到此資訊。
+ `environment_name` - 環境名稱。
+ `version_label` – 目前部署到提供請求之執行個體的應用程式版本名稱。
+ `deployment_id` – **數字**，指出上次成功部署到提供請求之執行個體的 ID。
+ `xray` – 有關所用檢測類型和版本的中繼資料。
+ `auto_instrumentation` – 布林值，指出是否使用自動檢測 （例如 Java 代理程式）。
+ `sdk_version` – 正在使用的 SDK 或代理程式版本。
+ `sdk` – SDK 的類型。
**Example AWS 具有外掛程式的 區塊**
```
"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"
}
}
```
針對子區段，記錄應用程式存取之 AWS 服務 和資源的相關資訊。X-Ray 會使用此資訊來建立推斷區段，代表服務映射中的下游服務。
**`aws` (子區段)**
所有欄位都是選擇性的。
+ `operation` – 針對 AWS 服務 或 資源叫用的 API 動作名稱。
+ `account_id` – 如果您的應用程式存取不同帳戶中的資源，或將客群傳送至不同帳戶，請記錄擁有應用程式存取之 AWS 資源的帳戶 ID。
+ `region` – 如果資源所在的區域與您的應用程式不同，請記錄區域。例如：`us-west-2`。
+ `request_id` – 請求的唯一識別符。
+ `queue_url` – 對於 Amazon SQS 佇列上的操作，則為佇列的 URL。
+ `table_name` – 對於 DynamoDB 資料表上的操作，則為資料表的名稱。
**Example 呼叫 DynamoDB 以儲存項目的子區段**
```
{
"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",
}
}
```
## 錯誤和例外狀況
當發生錯誤時，您可以記錄錯誤及其產生異常的相關詳細資訊。在您應用程式將錯誤傳回使用者時於區段中記錄錯誤，或是在下游呼叫傳回錯誤時於子區段中記錄錯誤。
**錯誤類型**
將一或多個以下欄位設為 `true` 來指出發生錯誤。若錯誤發生複合，則可套用多個類型。例如，來自下游呼叫的 `429 Too Many Requests` 錯誤可能會造成您的應用程式傳回 `500 Internal Server Error`；在這種情況下，即會套用三種類型。
+ `error` – **布林值**表示發生用戶端錯誤 （回應狀態碼為 4XX 用戶端錯誤）。
+ `throttle` – **布林值**，指出請求已調節 （回應狀態碼為 *429 太多請求*)。
+ `fault` – **布林值**表示發生伺服器錯誤 （回應狀態碼為 5XX 伺服器錯誤）。
透過在區段或子區段中包含一個**原因 (cause)** 物件來指出錯誤的原因。
**`cause`**
原因可以是 **16 字元**的異常 ID，或是具備以下欄位的物件：
+ `working_directory` – 發生例外狀況時工作目錄的完整路徑。
+ `paths` – 發生例外狀況時使用的程式庫或模組的路徑**陣列**。
+ `exceptions` – **例外**狀況物件的**陣列**。
在一或多個**異常 (exception)** 物件中包含錯誤的詳細資訊。
**`exception`**
所有欄位都是選擇性的。
+ `id` – 例外狀況的 64 位元識別符，在相同追蹤中的區段中是唯一的，以 **16 個十六進位數字**表示。
+ `message` – 例外狀況訊息。
+ `type` – 例外狀況類型。
+ `remote` – **布林值**，指出例外是由下游服務傳回的錯誤所造成。
+ `truncated` – **整數**，指出從 省略的堆疊影格數目`stack`。
+ `skipped` – **整數**，指出在此例外狀況及其子項之間略過的例外狀況數目，也就是它導致的例外狀況。
+ `cause` – 例外狀況的父系例外狀況 ID，也就是造成此例外狀況的例外狀況。
+ `stack` – **stackFrame** 物件****陣列。
若可用的話，在 **stackFrame** 物件中記錄呼叫堆疊的相關資訊。
**`stackFrame`**
所有欄位都是選擇性的。
+ `path` – 檔案的相對路徑。
+ `line` – 檔案中的行。
+ `label` – 函數或方法名稱。
## SQL 查詢
您可以建立為您應用程式對 SQL 資料庫發出的查詢建立子區段。
**`sql`**
所有欄位都是選擇性的。
+ `connection_string` – 對於不使用 URL 連線字串的 SQL Server 或其他資料庫連線，請記錄連線字串，但不包括密碼。
+ `url` – 對於使用 URL 連線字串的資料庫連線，請記錄 URL，不包括密碼。
+ `sanitized_query` – 資料庫查詢，其中任何使用者提供的值都會移除或由預留位置取代。
+ `database_type` – 資料庫引擎的名稱。
+ `database_version` – 資料庫引擎的版本編號。
+ `driver_version` – 您的應用程式使用的資料庫引擎驅動程式名稱和版本編號。
+ `user` – 資料庫使用者名稱。
+ `preparation` – `call` 如果查詢使用 `PreparedCall`；`statement`如果查詢使用 `PreparedStatement`。
**Example 使用 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=?;"
}
}
```