本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 X-Ray API
如果 X-Ray SDK 不支援您的程式設計語言，您可以直接使用 X-Ray APIs或 AWS Command Line Interface (AWS CLI) 來呼叫 X-Ray API 命令。使用下列指引來選擇您與 API 的互動方式：
+ 使用 使用預先格式化的命令或 請求中的選項 AWS CLI ，來使用更簡單的語法。
+ 直接使用 X-Ray API，以針對您對 X-Ray 提出的請求，獲得最大的彈性和自訂。
如果您直接使用 [X-Ray API](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) 而非 AWS CLI，則必須以正確的資料格式來參數化請求，也可能必須設定身分驗證和錯誤處理。
下圖顯示選擇如何與 X-Ray API 互動的指引：
![\[X-Ray 會顯示應用程式請求的詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/api-vs-cli.png)
使用 X-Ray API 將追蹤資料直接傳送到 X-Ray。X-Ray API 支援 X-Ray SDK 中提供的所有函數，包括下列常見動作：
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) – 將區段文件上傳至 X-Ray。
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) – 擷取追蹤 IDs 清單中的追蹤清單。每個擷取的追蹤都是來自單一請求的區段文件集合。
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) – 擷取追蹤IDs 和註釋。您可以指定 `FilterExpression`來擷取追蹤摘要的子集。
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html) – 擷取特定追蹤 ID 的服務圖表。
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) – 擷取JSON格式化文件，描述處理傳入請求和呼叫下游請求的服務。
您也可以使用應用程式程式碼中的 AWS Command Line Interface (AWS CLI)，以程式設計方式與 X-Ray 互動。 AWS CLI 支援 X-Ray SDK 中提供的所有函數，包括其他函數 AWS 服務。下列函數是先前以更簡單格式列出的 API 操作版本：
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html) – 將區段文件上傳至 X-Ray。
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html) – 擷取追蹤 IDs 清單中的追蹤清單。每個擷取的追蹤都是來自單一請求的區段文件集合。
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html) – 擷取追蹤IDs 和註釋。您可以指定 `FilterExpression`來擷取追蹤摘要的子集。
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html) – 擷取特定追蹤 ID 的服務圖表。
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html) – 擷取`JSON`格式化文件，描述處理傳入請求和呼叫下游請求的服務。
若要開始使用，您必須[AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)為作業系統安裝 。 AWS 支援 Linux、 macOS和 Windows 作業系統。如需 X-Ray 命令清單的詳細資訊，請參閱適用於 [AWS CLI X-Ray 的命令參考指南](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html)。
**Topics**
+ [搭配 CLI AWS 使用 AWS X-Ray API](xray-api-tutorial.md)
+ [將追蹤資料傳送至 AWS X-Ray](xray-api-sendingdata.md)
+ [從 取得資料 AWS X-Ray](xray-api-gettingdata.md)
+ [使用 AWS X-Ray API 設定取樣、群組和加密設定](xray-api-configuration.md)
+ [透過 X-Ray API 使用取樣規則](xray-api-sampling.md)
+ [AWS X-Ray 區段文件](xray-api-segmentdocuments.md)
# 搭配 CLI AWS 使用 AWS X-Ray API
CLI AWS 可讓您直接存取 X-Ray 服務，並使用 X-Ray 主控台用來擷取服務圖表和原始追蹤資料的相同 APIs。範例應用程式包含指令碼，示範如何將這些 APIs與 CLI AWS 搭配使用。
## 先決條件
此教學使用 Scorekeep 範例應用程式和隨附的指令碼，以產生追蹤資料和服務地圖。按照[入門教學](xray-gettingstarted.md)中的指示啟動應用程式。
本教學課程使用 AWS CLI 來顯示 X-Ray API 的基本使用方式。適用於 [Windows、Linux 和 OS-X 的](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) AWS CLI 提供所有人公有 APIs的命令列存取 AWS 服務。
**注意**
您必須驗證您的 AWS CLI 已設定為與 Scorekeep 範例應用程式建立所在的相同區域。
隨附的指令碼 (用來測試範例應用程式) 會使用 `cURL`，將流量傳送到 API 和 `jq` 以剖析輸出。您可以從 `jq` [stedolan.github.io](https://stedolan.github.io/jq/) 下載可執行檔，並從 下載`curl`可執行檔[https://curl.haxx.se/download.html](https://curl.haxx.se/download.html)。大多數的 Linux 和 OS X 安裝都包括 cURL。
## 產生追蹤資料
當遊戲進行中時，Web 應用程式會每隔幾秒鐘持續產生對 API 的流量，但只會產生一種類型的請求。使用 `test-api.sh` 指令碼來執行端對端案例，並在您測試 API 時產生更多元化的追蹤資料。
**使用 `test-api.sh` 指令碼**
1. 開啟 [Elastic Beanstalk 主控台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 導覽至您環境的[管理主控台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 複製頁面標頭的環境 **URL**。
1. 開啟 `bin/test-api.sh` 並將 API 的值取代為您環境的 URL。
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. 執行指令碼來產生對 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"]}
```
## 使用 X-Ray API
CLI AWS 為 X-Ray 提供的所有 API 動作提供命令，包括 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)和 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)。如需所使用的所有支援動作和資料類型詳細資訊，請參閱 [AWS X-Ray API 參考](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
```
指令碼會擷取最後 10 分鐘的服務圖表。
```
~/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'
```
指令碼會擷取前一分鐘和兩個分鐘之間產生的追蹤 URL。
```
~/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[*]'
```
指令碼會擷取前一分鐘和兩個分鐘之間產生的完整追蹤。
```
~/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
}
...
```
## 清除
終止您的 Elastic Beanstalk 環境以關閉 Amazon EC2 執行個體、DynamoDB 資料表和其他資源。
**若要終止您的 Elastic Beanstalk 環境**
1. 開啟 [Elastic Beanstalk 主控台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 導覽至您環境的[管理主控台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 選擇**動作**。
1. 選擇 **Terminate Environment (終止環境)**。
1. 選擇**終止**。
追蹤資料會在 30 天後自動從 X-Ray 刪除。
# 將追蹤資料傳送至 AWS X-Ray
您可以將追蹤資料以區段文件的形式傳送至 X-Ray。區段文件是一種 JSON 格式字串，包含您應用程式在處理請求時執行工作的相關資訊。您的應用程式可記錄其在區段中自行執行的工作相關資料，或是在子區段中使用下游服務和資源的工作相關資料。
區段會記錄您應用程式執行工作的相關資訊。區段最少會記錄其在任務上耗費的時間、名稱及兩個 ID。追蹤 ID 會在請求於服務間傳送時追蹤請求。區段 ID 會追蹤單一服務為請求完成的工作。
**Example 最小的完成區段**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
接收到請求時，您可以傳送正在進行中的區段做為預留位置，直到完成請求。
**Example 進行中的區段**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
您可以透過 [`PutTraceSegments`](#xray-api-segments)或透過 X-Ray [協助程式直接將區段傳送至 X-Ray](#xray-api-daemon)。
大多數應用程式會使用 AWS SDK 呼叫其他 服務或存取資源。在*子區段*中記錄下游呼叫的相關資訊。X-Ray 使用子區段來識別未傳送區段的下游服務，並在服務圖表上為其建立項目。
子區段可內嵌在完整區段文件中，或是分別傳送。個別傳送子區段，以非同步追蹤長時間執行請求的下游呼叫，或避免超過區段文件大小上限 (64 kB)。
**Example 子區段**
子區段具備 `subsegment` 的 `type`，以及可識別父區段的 `parent_id`。
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
如需您可以包含在區段和子區段中欄位和值的詳細資訊，請參閱 [AWS X-Ray 區段文件](xray-api-segmentdocuments.md)。
**Topics**
+ [產生追蹤 ID](#xray-api-traceids)
+ [使用 PutTraceSegments](#xray-api-segments)
+ [將區段文件傳送至 X-Ray 協助程式](#xray-api-daemon)
## 產生追蹤 ID
若要將資料傳送至 X-Ray，您必須為每個請求產生唯一的追蹤 ID。
**X-Ray 追蹤 ID 格式**
X-Ray `trace_id`由以連字號分隔的三個數字組成。例如 `1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。
例如，太平洋標準時間 2016 年 12 月 1 日上午 10：00，以秒`1480615200`為單位或以十六進位數字`58406520`為單位。
+ 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字表示**。
**注意**
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。傳送至 X-Ray 時，W3C 追蹤 ID 必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要這樣做。
您可以撰寫指令碼來產生 X-Ray IDs 進行測試。以下是兩個範例。
**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"
```
如需建立追蹤 IDs並將區段傳送至 X-Ray 協助程式的指令碼，請參閱 Scorekeep 範例應用程式。
+ 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)
## 使用 PutTraceSegments
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API 上傳區段文件。API 具備單一參數 (`TraceSegmentDocuments`)，會接受 JSON 區段文件清單。
使用 AWS CLI，使用 `aws xray put-trace-segments`命令將區段文件直接傳送至 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": []
}
```
**注意**
Windows 命令處理程式和 Windows PowerShell 針對在 JSON 字串中引述和逸出引述具有不同需求。如需詳細資訊，請參閱 AWS CLI 《 使用者指南》中的[引號字串](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)。
輸出會列出任何處理失敗的區段。例如，若追蹤 ID 內的日期為距離現在太遠的過去日期，您可能會看到如下的錯誤。
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
您可以同時傳遞多個區段文件，並以空格區隔。
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## 將區段文件傳送至 X-Ray 協助程式
您可以傳送區段和子區段至 X-Ray 協助程式，而不是將區段文件傳送至 X-Ray 協助程式，這會緩衝它們並批次上傳至 X-Ray API。X-Ray SDK 會將區段文件傳送至協助程式，以避免直接呼叫 AWS 。
**注意**
如需執行精靈的說明，請參閱[在本機執行 X-Ray 協助程式](xray-daemon-local.md)。
透過 UDP 連接埠 2000 以 JSON 傳送區段，並在前面加上精靈標頭 (`{"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"}
```
在 Linux 上，您可以從 Bash 終端機將區段文件傳送到精靈。將標頭和區段文件儲存到文字檔，並使用 `cat` 將它輸送到 `/dev/udp`。
```
$ 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"}
```
檢查[協助程式日誌](xray-daemon.md#xray-daemon-logging)，確認已將區段傳送至 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)
```
# 從 取得資料 AWS X-Ray
AWS X-Ray 會處理您傳送給它的追蹤資料，以在 JSON 中產生完整的追蹤、追蹤摘要和服務圖表。您可以使用 CLI 直接從 API AWS 擷取產生的資料。
**Topics**
+ [擷取服務圖表](#xray-api-servicegraph)
+ [根據群組擷取服務圖表](#xray-api-servicegraphgroup)
+ [擷取追蹤](#xray-api-traces)
+ [擷取和精簡根本原因分析](#xray-api-analytics)
## 擷取服務圖表
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) API 擷取 JSON 服務圖表。API 需要開始時間及結束時間。您可以從 Linux 終端機使用 `date` 命令來計算該時間。
```
$ date +%s
1499394617
```
`date +%s` 會印出日期 (秒)。使用此數字做為結束時間，並減去時間來取得開始時間。
**Example 擷取最後 10 分鐘服務圖表的指令碼**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
下列範例顯示具有 4 個節點的服務圖表，包括用戶端節點、EC2 執行個體、DynamoDB 資料表和 Amazon SNS 主題。
**Example GetServiceGraph 輸出**
```
{
"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
}
]
}
]
}
```
## 根據群組擷取服務圖表
若要根據群組的內容呼叫服務圖形，請包含 `groupName` 或 `groupARN`。以下範例為服務圖表呼叫名為 Example1 的群組。
**Example 根據名稱為 Example1 群組擷取服務圖表的指令碼**
```
aws xray get-service-graph --group-name "Example1"
```
## 擷取追蹤
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 取得追蹤摘要清單。追蹤摘要包含您可以用來識別要完整下載追蹤的資訊，包含標註、請求和回應資訊，以及 ID。
呼叫 `aws xray get-trace-summaries` 時有兩個 `TimeRangeType` 標記可用：
+ **TraceId** – 預設`GetTraceSummaries`搜尋使用 TraceID 時間，並傳回在計算`[start_time, end_time)`範圍內啟動的追蹤。此時間戳記範圍是根據 TraceId 中的時間戳記編碼計算，也可以手動定義。
+ **事件時間 **– 為了在一段時間內搜尋事件， AWS X-Ray 允許使用事件時間戳記搜尋追蹤。事件時間會傳回 `[start_time, end_time)` 範圍內作用中的追蹤，無論追蹤由何時開始。
使用 `aws xray get-trace-summaries` 命令來取得追蹤摘要清單。下列命令會使用預設的 TraceId 時間，取得 1 到 2 分鐘之間的追蹤摘要清單。
**Example 取得追蹤摘要的指令碼**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries 輸出**
```
{
"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
}
```
使用來自輸出的追蹤 ID 來透過 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 擷取完整追蹤。
**Example BatchGetTraces 命令**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces 輸出**
```
{
"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": []
}
```
完整追蹤包含每個區段的文件，該文件是從所有使用相同追蹤 ID 接收到的區段文件編譯而成。這些文件不代表您的應用程式傳送到 X-Ray 的資料。而是代表 X-Ray 服務產生的已處理文件。X-Ray 會編譯應用程式傳送的區段文件，並移除不符合[區段文件結構描述的資料，以建立完整的追蹤文件](xray-api-segmentdocuments.md)。
X-Ray 也會建立*推斷區段*，以便對不會自行傳送區段的服務進行下游呼叫。例如，當您使用經檢測的用戶端呼叫 DynamoDB 時，X-Ray SDK 會記錄子區段，其中包含從其觀點來看的呼叫詳細資訊。不過，DynamoDB 不會傳送對應的區段。X-Ray 會使用子區段中的資訊來建立推斷區段，以代表追蹤映射中的 DynamoDB 資源，並將其新增至追蹤文件。
若要從 API 取得多個追蹤，您需要追蹤 IDs清單，您可以使用 `get-trace-summaries` [AWS CLI 查詢](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter)從 輸出擷取。將清單重新導向至 的輸入`batch-get-traces`，以取得特定期間內的完整追蹤。
**Example 取得一分鐘期間完整追蹤的指令碼**
```
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[*]'
```
## 擷取和精簡根本原因分析
使用 [GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) 產生追蹤摘要時，可以其 JSON 格式重複使用部分追蹤摘要，以根本原因為基礎建立精簡的篩選條件表達式。如需精簡步驟的演練，請參閱以下範例。
**Example 範例 GetTraceSummaries 輸出 - 回應時間根本原因一節**
```
{
"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
}
]
}
]
}
```
透過編輯和忽略上述輸出，可利用此 JSON 篩選條件符合根本原因的實體。針對出現在 JSON 中的每一個欄位，任何待選項目必須完全相符，否則不會傳回追蹤。已移除的欄位會成為萬用字元值，與篩選條件表達式查詢結構相容的格式。
**Example 重新格式化回應時間根本原因**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
然後，此 JSON 會透過呼叫 `rootcause.json = #[{}]`，做為篩選條件表達式的一部分使用。如需查詢篩選條件表達式的詳細資訊，請參閱[篩選條件表達式](xray-console-filters.md)一章。
**Example 範例 JSON 篩選條件**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# 使用 AWS X-Ray API 設定取樣、群組和加密設定
AWS X-Ray 提供用於設定[取樣規則](xray-console-sampling.md)、群組規則和[加密設定的](xray-console-encryption.md) APIs。
**Topics**
+ [加密設定](#xray-api-configuration-encryption)
+ [抽樣規則](#xray-api-configuration-sampling)
+ [Groups (群組)](#xray-api-configuration-groups)
## 加密設定
使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)指定要用於加密的 AWS Key Management Service (AWS KMS) 金鑰。
**注意**
X-Ray 不支援非對稱 KMS 金鑰。
```
$ 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"
}
}
```
針對金鑰 ID，您可以使用別名 (如範例中所示)、金鑰 ID 或 Amazon Resource Name (ARN)。
使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) 以取得目前的組態。當 X-Ray 完成套用您的設定時，狀態會從 變更為 `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"
}
}
```
若要停止使用 KMS 金鑰並使用預設加密，請將加密類型設定為 `NONE`。
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## 抽樣規則
您可以使用 X-Ray API 管理帳戶中的[抽樣規則](xray-console-sampling.md)。如需新增和管理標籤的詳細資訊，請參閱 [標記 X-Ray 取樣規則和群組](xray-tagging.md)。
使用 [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
}
]
}
```
預設規則會套用至不符合其他規則的所有請求。這是優先順序最低的規則，且無法刪除。不過，您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) 變更速率和儲槽大小。
**Example 的 API 輸入 [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
}
}
```
以下範例使用之前的檔案做為輸入，將預設規則變更為 1%、無儲槽。標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。若要從抽樣規則中移除現有標籤，請使用 [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
},
```
使用 [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html) 建立額外的抽樣規則。當您建立規則時，大多數規則欄位都必須填寫。以下範例將建立兩個規則。第一個規則會設定 Scorekeep 範例應用程式的基本速率。此規則適用於所有 API 提供但不符合更高優先順序之規則的請求。
**Example 適用於 [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 的 API 輸入**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
第二個規則也會套用至 Scorekeep，但它的優先順序更高且更具體。此規則會設定非常低的抽樣速率以輪詢請求。這些是用戶端每隔幾秒發出的 GET 請求，以檢查遊戲狀態的變更。
**Example 適用於 [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 的 API 輸入**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。
```
$ 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
}
}
```
若要刪除抽樣規則，請使用 [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
}
}
```
## Groups (群組)
您可以使用 X-Ray API 來管理帳戶中的群組。群組是由篩選條件表達式定義的追蹤集合。您可以使用 群組來產生額外的服務圖表，並提供 Amazon CloudWatch 指標。[從 取得資料 AWS X-Ray](xray-api-gettingdata.md) 如需透過 X-Ray API 使用服務圖表和指標的詳細資訊，請參閱 。如需 群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。如需新增和管理標籤的詳細資訊，請參閱 [標記 X-Ray 取樣規則和群組](xray-tagging.md)。
使用 `CreateGroup` 建立群組 標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。
```
$ 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}"
}
```
使用 `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"
}
```
使用 `UpdateGroup` 更新群組 標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。若要從群組中移除現有標籤，請使用 [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}"
}
```
用 `DeleteGroup` 刪除群組。
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# 透過 X-Ray API 使用取樣規則
SDK AWS X-Ray 使用 X-Ray API 來取得取樣規則、報告取樣結果，以及取得配額。您可以使用這些 APIs 來進一步了解抽樣規則的運作方式，或以 X-Ray SDK 不支援的語言實作抽樣。
從使用 [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
}
]
}
```
輸出會包含預設規則和自訂規則。若您尚未建立抽樣規則，請參閱[抽樣規則](xray-api-configuration.md#xray-api-configuration-sampling)。
依照遞增優先順序排序，針對傳入請求評估規則。當規則相符時，使用固定速率和儲槽大小來進行抽樣決策。記錄抽樣請求並忽略 (針對追蹤用途) 未抽樣請求。在完成抽樣決策後停止評估規則。
規則儲槽大小是在套用固定速率前，每秒要記錄的追蹤目標數。儲槽會累積套用到所有服務，因此您無法直接使用它。不過，如果不是零，您可以從儲槽借用每秒一個追蹤，直到 X-Ray 指派配額為止。在接收配額前，記錄每秒的第一個請求，然後將固定速率套用到其他請求。固定速率是介於 0 和 1.00 (100%) 間的十進位數。
以下範例會顯示對 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) 發出的呼叫，其中包含在過去 10 秒間進行的抽樣決策詳細資訊。
```
$ 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": []
}
```
X-Ray 的回應包含要使用的配額，而不是從儲槽借用。在此範例中，服務在 10 秒間從儲槽借用 10 個追蹤，並將 10% 的固定速率套用到其他 100 個請求，其結果合計為 20 個抽樣請求。配額有效期為五分鐘 （以存留時間表示） 或直到指派新的配額為止。X-Ray 也可能指派比預設值更長的報告間隔，雖然不是在這裡。
**注意**
第一次呼叫時，來自 X-Ray 的回應可能不會包含配額。繼續從儲存借用，直到您獲得指派配額。
回應中的其他兩個欄位可能會指出輸入的問題。針對您最後一次呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 檢查 `LastRuleModification`。若其較新，請取得規則的新複本。`UnprocessedStatistics` 可包含錯誤，指出規則已遭到刪除、輸入中的統計文件過舊，或是許可錯誤。
# 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=?;"
}
}
```