AWS X-Ray 區段文件

必要的區段欄位

• 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-Ray 1-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以記錄區段已啟動但未完成。應用程式收到的請求需要很長時間時，請傳送進行中區段，以追蹤請求的接收情況。回應已傳送時，請傳送完成區段以覆寫進行中的區段。針對每個請求，請只傳送一個完成區段，以及一或零個進行中區段。

選擇性區段欄位

• 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物件陣列。

必要的子區段欄位

• 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-Ray 1-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

所有欄位都是選擇性的。

• 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— 整數，指出以位元組為單位的回應主體長度。

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 (子區段)

所有欄位都是選擇性的。

• operation— 針對 AWS 服務 或資源叫用的 API 動作名稱。

• account_id— 如果您的應用程式存取不同帳戶中的資源，或將區段傳送至其他帳戶，請記錄擁有應用程式存取之 AWS 資源的帳號 ID。

• region— 如果資源位於與您的應用程式不同的區域，請記錄該區域。例如 us-west-2。

• request_id— 要求的唯一識別碼。

• queue_url— 對於 Amazon SQS 佇列上的操作，則為佇列的 URL。

• table_name— 對於 DynamoDB 資料表上的作業，則為資料表的名稱。

錯誤類型

將一或多個以下欄位設為 true 來指出發生錯誤。若錯誤發生複合，則可套用多個類型。例如，來自下游呼叫的 429 Too Many Requests 錯誤可能會造成您的應用程式傳回 500 Internal Server Error；在這種情況下，即會套用三種類型。

• error— 布林值，表示發生用戶端錯誤 (回應狀態碼為 4XX 用戶端錯誤)。

• throttle— 布林值，表示要求已限制 (回應狀態碼為 429 要求太多)。

• fault— 布林值，表示發生伺服器錯誤 (回應狀態碼為 5XX 伺服器錯誤)。

cause

原因可以是 16 字元的異常 ID，或是具備以下欄位的物件：

• working_directory— 發生異常時工作目錄的完整路徑。

• paths— 發生例外狀況時所使用的程式庫或模組的路徑陣列。

• exceptions— 例外狀況物件的陣列。

exception

所有欄位都是選擇性的。

• id— 例外狀況的 64 位元識別碼，在相同追蹤中的區段中是唯一的，以 16 個十六進位數字表示。

• message— 例外狀況訊息。

• type— 例外狀況類型。

• remote— 布林值，表示例外狀況是由下游服務傳回的錯誤所造成。

• truncated— 整數，表示從省略的堆疊影格數目stack。

• skipped— 整數，表示在此例外狀況與其子系之間略過的例外狀況數目，也就是它所造成的例外狀況。

• cause— 例外父項的例外狀況識別碼，也就是造成此例外狀況的例外狀況。

• stack— stackFrame 物件的陣列。

stackFrame

所有欄位都是選擇性的。

• path— 檔案的相對路徑。

• line— 檔案中的行。

• label— 函數或方法名稱。

sql

所有欄位都是選擇性的。

• connection_string— 對於不使用 URL 連接字串的 SQL Server 或其他資料庫連線，請記錄連接字串 (不包括密碼)。

• url— 對於使用 URL 連線字串的資料庫連線，請記錄 URL，但不包括密碼。

• sanitized_query— 資料庫查詢，其中任何使用者提供的值會移除或取代為預留位置。

• database_type— 資料庫引擎的名稱。

• database_version— 資料庫引擎的版本號碼。

• driver_version— 應用程式使用的資料庫引擎驅動程式的名稱和版本號碼。

• user— 資料庫使用者名稱。

• preparation— call 如果查詢使用了PreparedCall；statement如果查詢使用PreparedStatement.