使用適用於 Python 的 X-Ray SDK 將註釋和中繼資料新增至區段

您可以使用註釋和中繼資料來記錄有關請求、環境或應用程式的其他資訊。您可以將註釋和中繼資料新增至 X-Ray SDK 建立的區段，或新增至您建立的自訂子區段。

註釋是與字符串，數字或布爾值鍵-值對。註釋會編製索引以與篩選器運算式搭配使用 使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 GetTraceSummaries API 時使用標記。

中繼資料是索引鍵-值配對，可以具有任何類型的值 (包括物件和清單)，但不會編製索引以供篩選運算式使用。使用元數據記錄要存儲在跟踪中但不需要與搜索一起使用的其他數據。

除了註釋和中繼資料，您也可以在區段上記錄使用者 ID 字串。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。

使用適用於 Python 的 X-Ray SDK 記錄註釋

針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。

註釋要求

• 按鍵 — X-Ray 註解的金鑰最多可包含 500 個英數字元。您不能使用底線符號 (_) 以外的空格或符號。

• 值 — X-Ray 註釋的值最多可包含 1,000 個 Unicode 字元。

• 註釋的數量 — 每個追蹤最多可以使用 50 個註釋。

記錄標註

1. 從 xray_recorder 取得目前區段或子區段的參考。

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

   或

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_subsegment()

2. 使用字串索引鍵、布林值、數字或字串值，呼叫 put_annotation。

   document.put_annotation("mykey", "my value");

或者，您可以使用 xray_recorder 上的 put_annotation 方法。此方法會在目前的子區段或區段 (若沒有任何開啟的子區段) 上記錄標註。

xray_recorder.put_annotation("mykey", "my value");

軟體開發套件會將標註以鍵/值對記錄在區段文件中的 annotations 物件內。若使用相同鍵呼叫 put_annotation 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

若要尋找具有特定值之註釋的繪線，請在篩選器運算式中使用annotations.key關鍵字。

使用適用於 Python 的 X-Ray SDK 記錄元數據

針對您不想要建立索引以用於搜尋的區段，請使用中繼資料來記錄這些區段或子區段上的資訊。中繼資料值可以是字串、數字、布林值，或可序列化為 JSON 物件或陣列的任何物件。

記錄中繼資料

1. 從 xray_recorder 取得目前區段或子區段的參考。

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

   或

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_subsegment()

2. 使用字串鍵、布林值、數字、字串或物件值，以及字串命名空間，呼叫 put_metadata。

   document.put_metadata("my key", "my value", "my namespace");

   或

   只使用鍵和值呼叫 put_metadata。

   document.put_metadata("my key", "my value");

或者，您可以使用 xray_recorder 上的 put_metadata 方法。此方法會在目前的子區段或區段 (若沒有任何開啟的子區段) 上記錄中繼資料。

xray_recorder.put_metadata("my key", "my value");

若您沒有指定命名空間，軟體開發套件會使用 default。若使用相同鍵呼叫 put_metadata 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

使用 X-Ray SDK 記錄用戶 ID

記錄請求區段上的使用者 ID 以識別傳送請求的使用者。

記錄使用者 ID

1. 從 xray_recorder 取得目前區段的參考。

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

2. 使用傳送請求之使用者的字串 ID 呼叫 setUser。

   document.set_user("U12345");

您可以在控制器中呼叫 set_user，以在應用程式開始處理請求時馬上記錄使用者 ID。

若要尋找使用者 ID 的追蹤，請在篩選運算式中使用user關鍵字。