設定適用於 Python 的 X-Ray 開發套件 - AWS X-Ray

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

設定適用於 Python 的 X-Ray 開發套件

注意

End-of-support通知 – 在 2027 年 2 月 25 日, AWS X-Ray 將停止支援 AWS X-Ray SDKs 和協助程式。2027 年 2 月 25 日之後,您將不再收到更新或版本。如需支援時間表的詳細資訊,請參閱 X-Ray SDK 和協助程式終止支援時間表。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊,請參閱從 X-Ray 檢測遷移至 OpenTelemetry 檢測

適用於 Python 的 X-Ray 開發套件具有名為 的類別xray_recorder,可提供全域記錄器。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的中介軟體。

服務外掛程式

使用 plugins 記錄託管您應用程式之服務的相關資訊。

外掛程式
  • Amazon EC2 – EC2Plugin 新增執行個體 ID、可用區域和 CloudWatch Logs 群組。

  • Elastic Beanstalk – ElasticBeanstalkPlugin 新增環境名稱、版本標籤和部署 ID。

  • Amazon ECS – ECSPlugin 新增容器 ID。

Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.

若要使用外掛程式,請在 xray_recorder 上呼叫 configure

from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all xray_recorder.configure(service='My app') plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin') xray_recorder.configure(plugins=plugins) patch_all()
注意

由於 plugins 是以元組形式傳入,請務必在指定單一外掛程式,時包含結尾。例如 plugins = ('EC2Plugin',)

您也可以使用優先於程式碼中設定值的環境變數,來設定記錄器。

修補程式庫前設定外掛程式來記錄下游呼叫。

軟體開發套件也會使用外掛程式設定來設定區段上的 origin 欄位。這表示執行您應用程式 AWS 的資源類型。當您使用多個外掛程式時,軟體開發套件會使用下列解析順序來判斷原始伺服器:ElasticBeanstalk > EKS > ECS > EC2。

抽樣規則

SDK 會使用您在 X-Ray 主控台中定義的抽樣規則來判斷要記錄哪些請求。預設規則每秒追蹤第一個請求,以及所有傳送追蹤至 X-Ray 服務的任何其他請求的 5%。在 X-Ray 主控台中建立其他規則,以自訂為每個應用程式記錄的資料量。

軟體開發套件會依定義自訂規則的順序套用自訂規則。如果請求符合多個自訂規則,則 SDK 只會套用第一個規則。

注意

如果 SDK 無法達到 X-Ray 以取得取樣規則,它會每秒還原為第一個請求的預設本機規則,以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs許可,或無法連線至 X-Ray 協助程式,該常駐程式充當 SDK 進行 API 呼叫的 TCP 代理,則可能會發生這種情況。

您也可以設定 SDK 從 JSON 文件載入抽樣規則。開發套件可以在 X-Ray 取樣無法使用的情況下,使用本機規則做為備份,或僅使用本機規則。

範例 sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } }

此範例定義了一個自訂規則和預設規則。自訂規則會套用 5% 的取樣率,沒有追蹤 下路徑的最低請求數/api/move/。預設規則會追蹤每秒的第一個請求和 10% 的額外請求。

在本機定義規則的缺點是,固定目標是由記錄器的每個執行個體獨立套用,而不是由 X-Ray 服務管理。當您部署更多主機時,固定速率會倍增,因此更難控制記錄的資料量。

在 上 AWS Lambda,您無法修改取樣率。如果您的函數是由 檢測服務呼叫,則 Lambda 將記錄產生該服務取樣之請求的呼叫。如果啟用主動追蹤且不存在追蹤標頭,Lambda 會做出抽樣決策。

若要設定備份抽樣規則,請呼叫 xray_recorder.configure (如以下範例所示),其中 rules 為規則的字典或指向包含抽樣規則 JSON 檔案的絕對路徑。

xray_recorder.configure(sampling_rules=rules)

若僅要使用本機規則,請使用 LocalSampler 設定記錄器。

from aws_xray_sdk.core.sampling.local.sampler import LocalSampler xray_recorder.configure(sampler=LocalSampler())

您也可以設定全域記錄器來停用所有傳入請求的抽樣和檢測。

範例 main.py – 停用取樣
xray_recorder.configure(sampling=False)

日誌

SDK 使用 Python 的內建logging模組搭配預設WARNING記錄層級。為 aws_xray_sdk 類別取得記錄器的參考,然後在其上呼叫 setLevel 來為程式庫及您其餘的應用程式設定不同日誌層級。

範例 app.py – 記錄
logging.basicConfig(level='WARNING') logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

當您手動產生子區段時,可使用除錯日誌來識別問題,例如未結束的子區段。

程式碼中的記錄器組態

可以從 xray_recorder 上的 configure 方法取得其他可用設定。

  • context_missing – 設定為 LOG_ERROR以避免在未開啟區段時,檢測程式碼嘗試記錄資料時擲回例外狀況。

  • daemon_address – 設定 X-Ray 協助程式接聽程式的主機和連接埠。

  • service – 設定 SDK 用於區段的服務名稱。

  • plugins – 記錄應用程式 AWS 資源的相關資訊。

  • sampling – 設定為 False以停用取樣。

  • sampling_rules – 設定包含取樣規則的 JSON 檔案路徑。

範例 main.py:// – 停用內容缺少例外狀況
from aws_xray_sdk.core import xray_recorder xray_recorder.configure(context_missing='LOG_ERROR')

使用 Django 的記錄器組態

若您使用 Django 框架,您可以使用 Django settings.py 檔案來在全域記錄器上設定選項。

  • AUTO_INSTRUMENT (僅限 Django) – 記錄內建資料庫和範本轉譯操作的子區段。

  • AWS_XRAY_CONTEXT_MISSING – 設定為 LOG_ERROR以避免在未開啟區段時,檢測程式碼嘗試記錄資料時擲回例外狀況。

  • AWS_XRAY_DAEMON_ADDRESS – 設定 X-Ray 協助程式接聽程式的主機和連接埠。

  • AWS_XRAY_TRACING_NAME – 設定軟體開發套件用於區段的服務名稱。

  • PLUGINS – 記錄應用程式 AWS 資源的相關資訊。

  • SAMPLING – 設定為 False以停用取樣。

  • SAMPLING_RULES – 設定包含取樣規則的 JSON 檔案路徑。

若要在 settings.py 中啟用記錄器組態,請將 Django 中介軟體新增至已安裝的應用程式清單。

範例 https://settings.py – 已安裝的應用程式
INSTALLED_APPS = [ ... 'django.contrib.sessions', 'aws_xray_sdk.ext.django', ]

在名為 XRAY_RECORDER 的字典中設定可用設定。

範例 https://settings.py – 已安裝的應用程式
XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR', 'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000', 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'), 'SAMPLING': False, }

環境變數

您可以使用環境變數來設定適用於 Python 的 X-Ray 開發套件。軟體開發套件支援以下變數:

  • AWS_XRAY_TRACING_NAME – 設定軟體開發套件用於區段的服務名稱。覆寫您以程式設計方式設定的服務名稱。

  • AWS_XRAY_SDK_ENABLED – 設為 時false, 會停用 SDK。軟體開發套件預設為啟用,除非環境變數設定為 false。

    • 停用時,全域記錄器會自動產生虛擬、不會傳送給協助程式的區段和子區段,且自動修補會停用。中介軟體是編寫做為透過全域記錄器的包裝函式。透過中介軟體產生的所有區段和子區段,也會成為虛擬區段和虛擬子區段。

    • 透過環境變數,或是透過與 aws_xray_sdk​ 程式庫內 global_sdk_config 物件的直接互動,設定 AWS_XRAY_SDK_ENABLED 的值。環境變數設定會覆寫這些互動。

  • AWS_XRAY_DAEMON_ADDRESS – 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設,軟體開發套件會使用 127.0.0.1:2000 進行追蹤資料 (UDP) 和取樣 (TCP)。如果您已設定協助程式在不同的連接埠上接聽,或在不同的主機上執行,請使用此變數。

    格式
    • 相同連接埠address:port

    • 不同的連接埠tcp:address:port udp:address:port

  • AWS_XRAY_CONTEXT_MISSING – 設定為 RUNTIME_ERROR 以在未開啟區段時,檢測程式碼嘗試記錄資料時擲回例外狀況。

    有效值
    • RUNTIME_ERROR – 捨棄執行時間例外狀況。

    • LOG_ERROR – 記錄錯誤並繼續 (預設)。

    • IGNORE_ERROR – 忽略錯誤並繼續。

    當您嘗試在未開啟請求時執行的啟動程式碼中使用經檢測用戶端,或在產生新執行緒的程式碼中,可能會發生與缺少區段或子區段相關的錯誤。

環境變數會覆寫程式碼中所設的值。