本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
使用 X-Ray API
如果 X-Ray SDK 不支援您的程式設計語言，您可以直接使用 X-Ray API，或使用 AWS Command Line Interface (AWS CLI) 呼叫 X-Ray API 指令。請使用下列指引來選擇與 API 互動的方式：
-
使用預先格式化的命令或請求中的選項來 AWS CLI 獲得更簡單的語法。
-
直接使用 X-Ray API 以獲得最大的靈活性，並針對您對 X-Ray 提出的請求進行自訂。
如果您直接使用 X-Ray API 而非使用 AWS CLI，則必須以正確的資料格式參數化要求，並且可能還必須設定驗證和錯誤處理。
下圖顯示選擇如何與 X-Ray API 互動的指引：
使用 X-Ray API 將追蹤資料直接傳送至 X-Ray。X-Ray API 支援 X-Ray SDK 中所有可用的功能，包括下列常見動作：
-
PutTraceSegments— 將區段文件上載至 X-Ray。
-
BatchGetTraces— 擷取追蹤 ID 清單中的追蹤清單。每個擷取的追蹤都是來自單一要求的區段文件集合。
-
GetTraceSummaries— 擷取追蹤的 ID 和註釋。您可以指定一個
FilterExpression來擷取追蹤摘要的子集。 -
GetTraceGraph— 擷取特定追蹤 ID 的服務圖形。
-
GetServiceGraph— 擷取JSON格式化文件，該文件描述處理傳入要求和呼叫下游要求的服務。
您也可以使用應用程式程式碼中的 AWS Command Line Interface (AWS CLI)，以程式設計方式與 X-Ray 互動。 AWS CLI 支援 X-Ray SDK 中可用的所有功能，包括其他功能 AWS 服務。以下函數是先前列出的 API 操作版本，格式更簡單：
-
put-trace-segments
— 將區段文件上載至 X-Ray。 -
batch-get-traces
— 擷取追蹤 ID 清單中的追蹤清單。每個擷取的追蹤都是來自單一要求的區段文件集合。 -
get-trace-summaries
— 擷取追蹤的 ID 和註釋。您可以指定一個 FilterExpression來擷取追蹤摘要的子集。 -
get-trace-graph
— 擷取特定追蹤 ID 的服務圖形。 -
get-service-graph
— 擷取 JSON格式化文件，該文件描述處理傳入要求和呼叫下游要求的服務。
若要開始使用，您必須AWS CLI為您的作業系統安裝。 AWS 支援LinuxmacOS和Windows作業系統。若要取得有關 X-Ray 指令清單的更多資訊，請參閱〈X-Ray 的指AWS CLI 令參考指南
探索 X-Ray API
X-Ray API 可透過 AWS SDK 或直接透過 HTTPS 存取所有 X-Ray 功能。 AWS Command Line InterfaceX-Ray API 參考會記錄每個 API 動作的輸入參數，以及它們傳回的欄位和資料類型。
您可以使用 AWS SDK 來開發使用 X-Ray API 的程式。X-Ray 控制台和 X-Ray 守護程序都使用 AWS SDK 與 X-Ray 進行通信。每種語言的 AWS SDK 都有對應至 X-Ray API 動作和類型之類別和方法的參考文件。
AWS SDK 參考資料
-
爪哇 — AWS SDK for Java
-
JavaScript – AWS SDK for JavaScript
-
.NET – AWS SDK for .NET
-
Ruby – AWS SDK for Ruby
-
前往 — AWS SDK for Go
-
PHP – AWS SDK for PHP
-
Python – AWS SDK for Python (Boto)
這 AWS Command Line Interface 是一個命令列工具，它使用適用於 Python 的 SDK 來呼叫 AWS API。當您第一次學習 AWS API 時， AWS CLI 提供了一種簡單的方法來探索可用的參數，並以 JSON 或文本形式查看服務輸出。
如需有關子指AWS CLI 令的詳細資訊，請參閱命aws xray令參考。
AWS CLI 可讓您直接存取 X-Ray 服務，並使用 X-Ray 主控台用來擷取服務圖表和原始追蹤資料的相同 API。範例應用程式包含指令碼，說明如何搭配 AWS CLI 使用這些 API。
必要條件
此教學使用 Scorekeep 範例應用程式和隨附的指令碼，以產生追蹤資料和服務地圖。遵循範例應用程式教學課程中的指示來啟動應用程式。
本教學課程使 AWS CLI 用顯示 X-Ray API 的基本用法。AWS CLI 可用於視窗、Linux 和 OS-X，為所有人提供對公用 API 的命令列存取。 AWS 服務
注意
您必須確認您的設定 AWS CLI 是否與建立範例應用程式的相同區域。
隨附的指令碼 (用來測試範例應用程式) 會使用 cURL，將流量傳送到 API 和 jq 以剖析輸出。您可以從 stedolan.github.jq執行文件，並從中下載可執行文件。curl https://curl.haxx.se/download.html
產生追蹤資料
當遊戲進行中時，Web 應用程式會每隔幾秒鐘持續產生對 API 的流量，但只會產生一種類型的請求。使用 test-api.sh 指令碼來執行端對端案例，並在您測試 API 時產生更多元化的追蹤資料。
使用 test-api.sh 指令碼
導覽至您環境的管理主控台。
-
複製頁面標頭的環境 URL。
-
開啟
bin/test-api.sh並將 API 的值取代為您環境的 URL。#!/bin/bash API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api -
執行指令碼來產生對 API 的流量。
~/debugger-tutorial$./bin/test-api.shCreating 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
AWS CLI 為 X-Ray 提供的所有 API 動作提供命令，包括GetServiceGraph和GetTraceSummaries。如需所使用的所有支援動作和資料類型詳細資訊，請參閱 AWS X-Ray API 參考。
範例 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",
...範例 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"
]範例 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 環境
導覽至您環境的管理主控台。
-
選擇動作。
-
選擇 Terminate Environment (終止環境)。
-
選擇終止。
追蹤資料會在 30 天後自動從 X-Ray 中刪除。
您可以將追蹤資料以區段文件的形式傳送至 X-Ray。區段文件是一種 JSON 格式字串，包含您應用程式在處理請求時執行工作的相關資訊。您的應用程式可記錄其在區段中自行執行的工作相關資料，或是在子區段中使用下游服務和資源的工作相關資料。
區段會記錄您應用程式執行工作的相關資訊。區段最少會記錄其在任務上耗費的時間、名稱及兩個 ID。追蹤 ID 會在請求於服務間傳送時追蹤請求。區段 ID 會追蹤單一服務為請求完成的工作。
範例 最小的完成區段
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}接收到請求時，您可以傳送正在進行中的區段做為預留位置，直到完成請求。
範例 進行中的區段
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}您可以使用 X 射線精靈直接PutTraceSegments、或透過 X-Ray 精靈將區段傳送至 X-Ray。
大多數應用程式都會使用 AWS SDK 呼叫其他服務或存取資源。記錄子區段中下游呼叫的相關資訊。X-Ray 使用子區段來識別不傳送區段的下游服務，並在服務圖上為其建立項目。
子區段可內嵌在完整區段文件中，或是分別傳送。分別傳送子區段，以非同步方式追蹤長時間執行要求的下游呼叫，或避免超過區段文件大小上限 (64 kB)。
範例 子區段
子區段具備 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”
}如需您可以包含在區段和子區段中欄位和值的詳細資訊，請參閱 X-Ray 段文件。
若要將資料傳送至 X-Ray，您必須為每個要求產生唯一的追蹤 ID。
X-Ray 軌跡 ID 格式
X-Ray trace_id 由三個用連字符分隔的數字組成。例如 1-58406520-a006649127e371903a2de979。其中包含：
-
版本號碼，也就是
1。 -
原始請求的時間在 Unix 紀元時間使用 8 個十六進制數字。
例如，2016 年 12 月 1 日上午 10:00 PST (以紀元時間表示) 為
1480615200秒或十六進58406520位數字。 -
追蹤的全域唯一 96 位元識別碼，以 24 個十六進位數字顯示。
注意
X-Ray 現在支援使用以 OpenTelemetry 及符合 W3C 追蹤上下文規格的任何其他架構建立的追蹤4efaaf4d1e8720b39541901950019ee5應格式化為傳送至 X-Ray 1-4efaaf4d-1e8720b39541901950019ee5 時。X-Ray 跟踪 ID 包括 Unix 紀元時間中的原始請求時間戳，但是在以 X-Ray 格式發送 W3C 跟踪 ID 時，這不是必需的。
您可以撰寫指令碼來產生 X-Ray 追蹤 ID 以進行測試。以下是兩個範例。
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"如需建立追蹤 ID 並將區段傳送至 X-Ray 精靈的指令碼，請參閱 Scorekeep 範例應用程式。
-
Python –
xray_start.py -
巴什 —
xray_start.sh
您可以使用 PutTraceSegments 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 使用指南》中的引用字串。
輸出會列出任何處理失敗的區段。例如，若追蹤 ID 內的日期為距離現在太遠的過去日期，您可能會看到如下的錯誤。
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}您可以同時傳遞多個區段文件，並以空格區隔。
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"您可以將區段和子區段傳送至 X-Ray API，而不是將區段文件傳送至 X-Ray API，而是將區段和子區段進行緩衝，並分批上傳至 X-Ray API。X-Ray SDK 會將區段文件傳送至精靈，以避免 AWS 直接呼叫。
注意
如需執行精靈的說明，請參閱在本機執行 X-Ray 精靈。
透過 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範例 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"}檢查精靈記錄檔，確認是否將區段傳送至 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)X-Ray 會處理您傳送給它的追蹤資料，以便以 JSON 格式產生完整追蹤、追蹤摘要和服務圖表。您可以使用 AWS CLI 直接從 API 擷取產生的資料。
您可以使用 GetServiceGraph API 擷取 JSON 服務圖表。API 需要開始時間及結束時間。您可以從 Linux 終端機使用 date 命令來計算該時間。
$ date +%s
1499394617date +%s 會印出日期 (秒)。使用此數字做為結束時間，並減去時間來取得開始時間。
範例 擷取最後 10 分鐘服務圖表的指令碼
EPOCH=$(date +%s) aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
下列範例顯示包含 4 個節點的服務圖表，其中包括一個用戶端節點、EC2 執行個體、一個 DynamoDB 表和一個 Amazon SNS 主題。
範例 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 的群組。
範例 根據名稱為 Example1 群組擷取服務圖表的指令碼
aws xray get-service-graph --group-name "Example1"
您可以使用 GetTraceSummaries 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 分鐘之間的追蹤摘要清單。
範例 取得追蹤摘要的指令碼
EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
範例 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 來透過 BatchGetTraces API 擷取完整追蹤。
範例 BatchGetTraces 命令
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b範例 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 會編譯應用程式傳送的區段文件，並移除不符合區段文件結構描述的資料，以建立完整的追蹤文件。如需詳細資訊，請參閱 X-Ray 段文件。
X-Ray 也會針對未傳送區段本身的服務的下游呼叫建立推斷的區段。例如，當您使用已檢測的用戶端呼叫 DynamoDB 時，X-Ray SDK 會記錄一個子區段，其中包含有關呼叫的詳細資訊。但是，DynamoDB 不會傳送對應的區段。X-Ray 會使用子區段中的資訊建立推斷的區段，以代表追蹤對應中的 DynamoDB 資源，並將其新增至追蹤文件。
要從 API 獲取多個跟踪，您需要一個跟踪 ID 的列表，您可以get-trace-summaries使用AWS CLI 查詢從的輸出中提取該列表。將清單重新導向batch-get-traces至的輸入，以取得特定時段的完整追蹤。
範例 取得一分鐘期間完整追蹤的指令碼
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 產生追蹤摘要時，部分追蹤摘要可以 JSON 格式重複使用，以根據根本原因建立精簡的篩選器運算式。如需精簡步驟的演練，請參閱以下範例。
範例 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 中的每一個欄位，任何待選項目必須完全相符，否則不會傳回追蹤。已移除的欄位會成為萬用字元值，與篩選條件表達式查詢結構相容的格式。
範例 重新格式化回應時間根本原因
{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [ { "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }
然後，此 JSON 會透過呼叫 rootcause.json = #[{}]，做為篩選條件表達式的一部分使用。如需有關使用篩選器運算式進行查詢的詳細資訊，請參閱瀏覽 X-Ray 主控台中的使用篩選器運算式
範例 JSON 篩選條件
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
X-Ray 提供用於設定取樣規則、群組規則和加密設定的 API。
加密設定
用PutEncryptionConfig於指定用於加密的 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)。
使用 GetEncryptionConfig 以取得目前的組態。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 管理帳戶中的取樣規則。如需取樣的更多資訊，請參閱設定取樣規則。如需新增和管理標籤的詳細資訊，請參閱標記 X-Ray 取樣規則和群組。
使用 GetSamplingRules 取得所有抽樣規則。
$ 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
}
]
}預設規則會套用至不符合其他規則的所有請求。這是優先順序最低的規則，且無法刪除。不過，您可以使用 UpdateSamplingRule 變更速率和儲槽大小。
範例 用於 UpdateSamplingRule— 1000 預設的 .json 的 API 輸入
{ "SamplingRuleUpdate": { "RuleName": "Default", "FixedRate": 0.01, "ReservoirSize": 0 } }
以下範例使用之前的檔案做為輸入，將預設規則變更為 1%、無儲槽。標籤是選擇性的。如果您選擇新增標籤，則需要標籤鍵，且標籤值是選擇性的。若要從取樣規則中移除現有標籤，請使用UntagResource。
$ 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
},
使用 CreateSamplingRule 建立額外的抽樣規則。當您建立規則時，大多數規則欄位都必須填寫。以下範例將建立兩個規則。第一個規則會設定 Scorekeep 範例應用程式的基本速率。此規則適用於所有 API 提供但不符合更高優先順序之規則的請求。
範例 用於 UpdateSamplingRule— 900 基於記分的 .json 的 API 輸入
{ "SamplingRule": { "RuleName": "base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1 } }
第二個規則也會套用至 Scorekeep，但它的優先順序更高且更具體。此規則會設定非常低的抽樣速率以輪詢請求。這些是用戶端每隔幾秒發出的 GET 請求，以檢查遊戲狀態的變更。
範例 API 輸入 UpdateSamplingRule— 5000 輪詢記分保持 .json
{ "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
}
}若要刪除抽樣規則，請使用 DeleteSamplingRule。
$ 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
}
}您可以使用 X-Ray API 來管理帳戶中的群組。群組是一系列追蹤，為篩選條件表達式所定義。您可以使用群組產生其他服務圖表並提供 Amazon CloudWatch 指標。從 X-Ray 獲取數據如需透過 X-Ray API 使用服務圖表和指標的更多詳細資訊，請參閱。如需群組的詳細資訊，請參閱設定群組。如需新增和管理標籤的詳細資訊，請參閱標記 X-Ray 取樣規則和群組。
使用 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。
$ 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 SDK 使用 X-Ray API 取得取樣規則、報告抽樣結果並取得配額。您可以使用這些 API 來更好地瞭解取樣規則的運作方式，或使用 X-Ray SDK 不支援的語言來實作取樣。
從使用 GetSamplingRules 取得所有抽樣規則開始。
$ 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
}
]
}
輸出會包含預設規則和自訂規則。若您尚未建立抽樣規則，請參閱使用 X-Ray API 設定取樣、群組和加密設定。
依照遞增優先順序排序，針對傳入請求評估規則。當規則相符時，使用固定速率和儲槽大小來進行抽樣決策。記錄抽樣請求並忽略 (針對追蹤用途) 未抽樣請求。在完成抽樣決策後停止評估規則。
規則儲槽大小是在套用固定速率前，每秒要記錄的追蹤目標數。儲槽會累積套用到所有服務，因此您無法直接使用它。但是，如果它不是零，則可以每秒從儲存器借用一條軌跡，直到 X-Ray 指定配額為止。在接收配額前，記錄每秒的第一個請求，然後將固定速率套用到其他請求。固定速率是介於 0 和 1.00 (100%) 間的十進位數。
以下範例會顯示對 GetSamplingTargets 發出的呼叫，其中包含在過去 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 的回應可能不會在您第一次呼叫時包含配額。繼續從儲存借用，直到您獲得指派配額。
回應中的其他兩個欄位可能會指出輸入的問題。針對您最後一次呼叫 GetSamplingRules 檢查 LastRuleModification。若其較新，請取得規則的新複本。UnprocessedStatistics 可包含錯誤，指出規則已遭到刪除、輸入中的統計文件過舊，或是許可錯誤。
追蹤區段是您應用程式所處理請求的 JSON 表示。追蹤區段會記錄原始要求的相關資訊、應用程式在本機執行之工作的相關資訊，以及子區段，其中包含應用程式對 AWS 資源、HTTP API 和 SQL 資料庫進行之下游呼叫的相關資訊。
段文件會將有關區段的資訊傳達至 X-Ray。區段文件最多可達 64 kB，且包含具有子區段的整個區段、指出要求正在進行的區段片段，或是個別傳送的單一子區段。您可以使用 PutTraceSegmentsAPI 將區段文件直接傳送至 X-Ray。
X-Ray 會編譯和處理區段文件，以產生可查詢的追蹤摘要和完整追蹤，您可以分別使用GetTraceSummaries和 BatchGetTracesAPI 存取這些摘要。除了您傳送至 X-Ray 的區段和子區段之外，服務還會使用子區段中的資訊來產生推斷的區段，並將其新增至完整追蹤。推斷的區段代表追蹤對映中的下游服務和資源。
X-Ray 提供區段文件的 JSON 結構定義。您可以在此處下載架構：xray-segmentdocument-schema-v1.0.0。以下章節會更詳細的說明結構描述中所列出的欄位和物件。
區段欄位的子集會由 X-Ray 編製索引，以便與篩選運算式搭配使用。例如，如果您將區段上的user欄位設定為唯一識別碼，您可以在 X-Ray 主控台或使用 GetTraceSummaries API 搜尋與特定使用者相關聯的區段。如需詳細資訊，請參閱 使用篩選表示式。
當您使用 X-Ray SDK 檢測應用程式時，SDK 會為您產生區段文件。SDK 不會將區段文件直接傳送至 X-Ray，而是透過本機 UDP 連接埠將它們傳送至 X-Ray 精靈。如需詳細資訊，請參閱 將區段文件傳送至 X-Ray 精靈。
區段會記錄您應用程式所處理請求的相關追蹤資訊。區段最少會記錄請求的名稱、ID、開始時間、追蹤 ID 及結束時間。
範例 最小的完成區段
{
"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。 -
原始請求的時間在 Unix 紀元時間使用 8 個十六進制數字。
例如，2016 年 12 月 1 日上午 10:00 PST (以紀元時間表示) 為
1480615200秒或十六進58406520位數字。 -
追蹤的全域唯一 96 位元識別碼，以 24 個十六進位數字顯示。
注意
X-Ray 現在支援使用以 OpenTelemetry 及符合 W3C 追蹤上下文規格的任何其他架構建立的追蹤
ID。傳送至 X-Ray 時，W3C 追蹤識別碼必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤識別碼 4efaaf4d1e8720b39541901950019ee5應格式化為傳送至 X-Ray1-4efaaf4d-1e8720b39541901950019ee5時。X-Ray 跟踪 ID 包括 Unix 紀元時間中的原始請求時間戳，但是在以 X-Ray 格式發送 W3C 跟踪 ID 時，這不是必需的。追蹤 ID 安全
您可在回應標頭中取得追蹤 ID。使用安全的隨機演算法產生追蹤 ID，以確保攻擊者無法計算未來的追蹤 ID，並使用這些 ID 傳送請求到您的應用程式。
-
-
start_time— 數字，表示區段建立的時間，以紀元時間為單位的浮點秒數。例如1480615200.010或1.480615200010E9。視需要使用任意小數位數。建議盡可能使用毫秒解析度。 -
end_time-數字，即段被關閉的時間。例如1480615200.090或1.480615200090E9。指定end_time或in_progress。 -
in_progress— 布林值，設定為true而非指定end_time以記錄區段已啟動但未完成。應用程式收到的請求需要很長時間時，請傳送進行中區段，以追蹤請求的接收情況。回應已傳送時，請傳送完成區段以覆寫進行中的區段。針對每個請求，請只傳送一個完成區段，以及一或零個進行中區段。
服務名稱
區段name應與產生區段之服務的網域名稱或邏輯名稱相符。但是，這不是強制執行的。具有PutTraceSegments可傳送任何名稱之區段之權限的任何應用程式。
以下欄位是區段的選擇性欄位。
選擇性區段欄位
-
service— 包含應用程式相關資訊的物件。-
version— 字串，用來識別提供要求的應用程式版本。
-
-
user— 識別傳送要求之使用者的字串。 -
origin— 執行應用程式的 AWS 資源類型。支援值
-
AWS::EC2::Instance— 一個 Amazon EC2 實例。 -
AWS::ECS::Container— 一個 Amazon ECS 容器. -
AWS::ElasticBeanstalk::Environment— Elastic Beanstalk 環境。
當有多個值適用您的應用程式時，請使用最具指定性的。例如，多容器泊塢視窗 Elastic Beanstalk 環境會在 Amazon ECS 容器上執行您的應用程式，然後在 Amazon EC2 執行個體上執行。在此案例中，您會將來源設為
AWS::ElasticBeanstalk::Environment，因為環境是其他兩個資源的父系。 -
-
parent_id— 您指定的子區段 ID 是否來自已檢測的應用程式的要求。X-Ray SDK 會將父子區段識別碼新增至追蹤標頭，以供下游 HTTP 呼叫使用。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。 -
http— 包含原始 HTTP 要求相關資訊的http物件。 -
aws— aws物件，其中包含應用程式提供要求之 AWS 資源的相關資訊。 -
error、throttlefault、和cause— 錯誤欄位，指出發生錯誤，其中包含造成錯誤之例外狀況的相關資訊。 -
annotations— 具有要 X-Ray 索引以進行搜尋的索引鍵值配對的annotations物件。 -
metadata— metadata含有您要儲存在區段中的任何其他資料的物件。 -
subsegments— subsegment物件陣列。
您可以建立子區段，以記錄您使用 AWS SDK 進行的呼叫 AWS 服務 和資源、呼叫內部或外部 HTTP Web API 或 SQL 資料庫查詢。您也可以建立子區段，除錯或標註您應用程式中的程式碼區塊。子區段可包含其他子區段，因此記錄內部函數呼叫中繼資料的自訂子區段可包含其他自訂子區段及下游呼叫的子區段。
子區段會從呼叫該呼叫的服務的角度記錄下游呼叫。X-Ray 使用子區段來識別不傳送區段的下游服務，並在服務圖上為其建立項目。
子區段可內嵌在完整區段文件中，或是分別傳送。將子區段分別傳送，來非同步追蹤長時間執行請求的下游呼叫，或是避免超過區段文件大小上限。
範例 具有內嵌子區段的區段
獨立子區段具備 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 已收到請求，然後在完成原始請求之前分別傳送子區段以追蹤它們。
範例 進行中的區段
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}範例 獨立子區段
獨立子區段具備 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— 數字，即創建子段的時間，以時代時間為單位的浮點秒，精確到毫秒。例如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。 -
原始請求的時間在 Unix 紀元時間使用 8 個十六進制數字。
例如，2016 年 12 月 1 日上午 10:00 PST (以紀元時間表示) 為
1480615200秒或十六進58406520位數字。 -
追蹤的全域唯一 96 位元識別碼，以 24 個十六進位數字顯示。
注意
X-Ray 現在支援使用以 OpenTelemetry 及符合 W3C 追蹤上下文規格的任何其他架構建立的追蹤
ID。傳送至 X-Ray 時，W3C 追蹤識別碼必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤識別碼 4efaaf4d1e8720b39541901950019ee5應格式化為傳送至 X-Ray1-4efaaf4d-1e8720b39541901950019ee5時。X-Ray 跟踪 ID 包括 Unix 紀元時間中的原始請求時間戳，但是在以 X-Ray 格式發送 W3C 跟踪 ID 時，這不是必需的。 -
-
parent_id— 子區段父項區段的區段 ID。僅在分別傳送子區段時才為必要項目。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。 -
type—subsegment. 僅在分別傳送子區段時才需要。
以下欄位是子區段的選擇性欄位。
選擇性子區段欄位
-
namespace—aws適用於 AWS 開發套件呼叫；remote適用於其他下游呼叫。 -
http— 包http含傳出 HTTP 呼叫相關資訊的物件。 -
aws— 包含應用程式呼叫之下游 AWS 資源相關資訊的aws物件。 -
error、throttlefault、和cause— 錯誤欄位，指出發生錯誤，其中包含造成錯誤之例外狀況的相關資訊。 -
annotations— 具有您希望 X-Ray 索引以進行搜尋的索引鍵值配對的annotations物件。 -
metadata— metadata含有您要儲存在區段中的任何其他資料的物件。 -
subsegments— subsegment物件陣列。 -
precursor_ids— 子區段 ID 陣列，可識別在此子區段之前完成的相同父項的子區段。
使用 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 會將追蹤視為中斷，直到下游服務上傳符合包含此區塊id之子區段的區段為止。parent_id
-
-
response— 有關響應的信息。-
status— 整數，表示回應的 HTTP 狀態。 -
content_length— 整數，指出以位元組為單位的回應主體長度。
-
當您檢測對下游 Web API 的呼叫時，請記錄一個子區段，其中包含 HTTP 要求和回應的相關資訊。X-Ray 會使用子區段來產生遠端 API 的推斷區段。
範例 在 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
}
}範例 下游 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
}
}
}範例 下游 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 個註釋。
範例 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物件，其中包含任何類型的值，包括物件和陣列。X-Ray 不會為中繼資料建立索引，而且值可以是任何大小，只要區段文件不超過最大大小 (64 kB) 即可。您可以在 BatchGetTraces API 傳回的完整區段文件中檢視中繼資料。以開頭的欄位金鑰 (debug在下列範例中) AWS. 會保留給 AWS提供的 SDK 和用戶端使用。
範例 使用中繼資料的自訂子區段
{
"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 物件包含您應用程式於其上執行的資源相關資訊。可將多個欄位套用至單一資源。例如，在 Elastic Beanstalk 上的多容器 Docker 環境中執行的應用程式可能會取得有關 Amazon EC2 執行個體、在執行個體上執行的 Amazon ECS 容器，以及 Elastic Beanstalk 環境本身的相關資訊。
aws (區段)
所有欄位都是選擇性的。
-
account_id— 如果您的應用程式將區段傳送至其他區段 AWS 帳戶，請記錄執行應用程式的帳戶 ID。 -
cloudwatch_logs— 描述單一 CloudWatch 記錄群組的物件陣列。-
log_group—「記 CloudWatch 錄群組」名稱。 -
arn— 記 CloudWatch 錄群組 ARN。
-
-
ec2— 有關 Amazon EC2 執行個體的資訊。-
instance_id— EC2 執行個體的執行個體識別碼。 -
instance_size— EC2 執行個體的類型。 -
ami_id— Amazon 機器圖像 ID. -
availability_zone— 執行執行個體所在的可用區域。
-
-
ecs— 有關 Amazon ECS 容器的信息。-
container— 容器的主機名稱。 -
container_id— 容器的完整容器 ID。 -
container_arn— 容器執行個體的 ARN。
-
-
eks— 有關 Amazon EKS 集群的信息。-
pod— 您的 EKS 網繭的主機名稱。 -
cluster_name— EKS 叢集名稱。 -
container_id— 容器的完整容器 ID。
-
-
elastic_beanstalk— 有關 Elastic Beanstalk 環境的信息。您可以在最新的 Elastic Beanstalk 平台/var/elasticbeanstalk/xray/environment.conf上命名的文件中找到此信息。-
environment_name- 環境名稱。 -
version_label— 目前部署至提供要求之執行個體的應用程式版本名稱。 -
deployment_id— 代表上次成功部署至提供要求之執行個體的識別碼的數字。
-
-
xray— 有關所使用儀器類型和版本的中繼資料。-
auto_instrumentation— 布林值，指出是否使用自動分析 (例如 Java 代理程式)。 -
sdk_version— 所使用的 SDK 或代理程式版本。 -
sdk— SDK 的類型。
-
範例 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 資料表上的作業，則為資料表的名稱。
範例 呼叫 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— 例外父項的例外狀況識別碼，也就是造成此例外狀況的例外狀況。 -
stack— stackFrame 物件的陣列。
若可用的話，在 stackFrame 物件中記錄呼叫堆疊的相關資訊。
stackFrame
所有欄位都是選擇性的。
-
path— 檔案的相對路徑。 -
line— 檔案中的行。 -
label— 函數或方法名稱。
您可以建立為您應用程式對 SQL 資料庫發出的查詢建立子區段。
sql
所有欄位都是選擇性的。
-
connection_string— 對於不使用 URL 連接字串的 SQL Server 或其他資料庫連線，請記錄連接字串 (不包括密碼)。 -
url— 對於使用 URL 連線字串的資料庫連線，請記錄 URL，但不包括密碼。 -
sanitized_query— 資料庫查詢，其中任何使用者提供的值會移除或取代為預留位置。 -
database_type— 資料庫引擎的名稱。 -
database_version— 資料庫引擎的版本號碼。 -
driver_version— 應用程式使用的資料庫引擎驅動程式的名稱和版本號碼。 -
user— 資料庫使用者名稱。 -
preparation—call如果查詢使用了PreparedCall；statement如果查詢使用PreparedStatement.
範例 使用 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=?;"
}
}