SDK為 Python 配置 X-Ray - AWS X-Ray
服務外掛程式抽樣規則日誌程式碼中的記錄器組態使用 Django 的記錄器組態環境變數

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

SDK為 Python 配置 X-Ray

Python SDK 的 X-Ray 有一個名xray_recorder為提供全局記錄器的類。您可以設定全域記錄器，以自訂建立來HTTP電區段的中介軟體。

服務外掛程式

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

外掛程式

  • Amazon EC2 — EC2Plugin 新增執行個體 ID、可用區域和 CloudWatch 日誌群組。

  • 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',)

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

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

SDK也會使用外掛程式設定來設定區origin段上的欄位。這表示運行您的應用程序的 AWS 資源的類型。當您使用多個外掛程式時，SDK會使用下列解析度順序來決定原點： ElasticBeanstalk EKS> ECS > > EC2。

抽樣規則

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

會依照SDK定義規則的順序套用自訂規則。如果要求符合多個自訂規則，則只會SDK套用第一個規則。

注意

如果無法達到 X-Ray SDK 以取得取樣規則，則會回復為每秒第一個要求的預設本機規則，而每個主機的任何其他要求的百分之五。如果主機沒有呼叫取樣的權限APIs，或者無法連線至 X-Ray 精靈 (做為SDK. TCP API

您也可以配置SDK為從JSON文件載入取樣規則。對於無法使用 X-Ray 取樣的情況，SDK可以使用本機規則做為備份，或僅使用本機規則。

範例 採樣規則
{
  "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
  }
}

此範例定義了一個自訂規則和一個預設規則。自訂規則會套用百分之五的取樣率，而且沒有追蹤下限路徑的要求數目下/api/move/限。預設規則會每秒追蹤第一個要求，以及 10% 的額外要求。

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

開啟時 AWS Lambda，您無法修改取樣率。如果您的函數是由已檢測的服務呼叫，則 Lambda 會記錄產生由該服務取樣之請求的呼叫。如果啟用主動追蹤且沒有追蹤標頭，Lambda 會做出取樣決策。

若要設定備份取樣規則xray_recorder.configure，請呼叫，如下列範例所示，where 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— 設定SDK用於區段的服務名稱。

  • PLUGINS— 記錄有關應用程序 AWS 資源的信息。

  • SAMPLING— 設定False為停用取樣。

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

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

範例 settings.py — 已安裝應用程式
INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

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

範例 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 SDK 的 X-Ray。支SDK援下列變數：

  • AWS_XRAY_TRACING_NAME— 設定SDK用於區段的服務名稱。覆寫您以程式設計方式設定的服務名稱。

  • AWS_XRAY_SDK_ENABLED— 設定為時false，會停用SDK。依預設，除非環境變數設定為 false，否則會啟用。SDK

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

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

  • AWS_XRAY_DAEMON_ADDRESS— 設定 X-Ray 精靈監聽程式的主機和連接埠。默認情況下，SDK用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— 忽略錯誤並繼續。

    當您嘗試在沒有要求開啟時執行的啟動程式碼中使用已檢測的用戶端，或在產生新執行緒的程式碼中使用已檢測的用戶端時，可能會發生與遺失區段或子區段相關的錯誤。

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