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

# 設定適用於 Python 的 X-Ray 開發套件
<a name="xray-sdk-python-configuration"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。

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

**Topics**
+ [服務外掛程式](#xray-sdk-python-configuration-plugins)
+ [抽樣規則](#xray-sdk-python-configuration-sampling)
+ [日誌](#xray-sdk-python-configuration-logging)
+ [程式碼中的記錄器組態](#xray-sdk-python-middleware-configuration-code)
+ [使用 Django 的記錄器組態](#xray-sdk-python-middleware-configuration-django)
+ [環境變數](#xray-sdk-python-configuration-envvars)

## 服務外掛程式
<a name="xray-sdk-python-configuration-plugins"></a>

使用 `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.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)


若要使用外掛程式，請在 `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',)` 

您也可以使用優先於程式碼中設定值的[環境變數](#xray-sdk-python-configuration-envvars)，來設定記錄器。

在[修補程式庫](xray-sdk-python-patching.md)前設定外掛程式來記錄下游呼叫。

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

## 抽樣規則
<a name="xray-sdk-python-configuration-sampling"></a>

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

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

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

您也可以設定 SDK 從 JSON 文件載入抽樣規則。對於無法使用 X-Ray 取樣的情況，軟體開發套件可以使用本機規則作為備份，或僅使用本機規則。

**Example 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())
```

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

**Example main.py – 停用取樣**  

```
xray_recorder.configure(sampling=False)
```

## 日誌
<a name="xray-sdk-python-configuration-logging"></a>

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

**Example app.py – 記錄**  

```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```

當您[手動產生子區段](xray-sdk-python-subsegments.md)時，可使用除錯日誌來識別問題，例如未結束的子區段。

## 程式碼中的記錄器組態
<a name="xray-sdk-python-middleware-configuration-code"></a>

可以從 `xray_recorder` 上的 `configure` 方法取得其他可用設定。
+ `context_missing` – 設定為 `LOG_ERROR`以避免在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。
+ `daemon_address` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。
+ `service` – 設定 SDK 用於區段的服務名稱。
+ `plugins` – 記錄應用程式 AWS 資源的相關資訊。
+ `sampling` – 設定為 `False`以停用取樣。
+ `sampling_rules` – 設定包含[取樣規則](#xray-sdk-python-configuration-sampling)的 JSON 檔案路徑。

**Example main.py：// – 停用內容缺少例外狀況**  

```
from aws_xray_sdk.core import xray_recorder

xray_recorder.configure(context_missing='LOG_ERROR')
```

## 使用 Django 的記錄器組態
<a name="xray-sdk-python-middleware-configuration-django"></a>

若您使用 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` – 設定包含[取樣規則](#xray-sdk-python-configuration-sampling)的 JSON 檔案路徑。

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

**Example https：//settings.py – 已安裝的應用程式**  

```
INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]
```

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

**Example 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,
}
```

## 環境變數
<a name="xray-sdk-python-configuration-envvars"></a>

您可以使用環境變數來設定適用於 Python 的 X-Ray 開發套件。軟體開發套件支援以下變數：
+ `AWS_XRAY_TRACING_NAME` – 設定 SDK 用於區段的服務名稱。覆寫您以程式設計方式設定的服務名稱。
+ `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)。如果您已設定協助程式在[不同的連接埠上接聽](xray-daemon-configuration.md)，或在不同的主機上執行，請使用此變數。

**格式**
  + **相同連接埠** – `address:port`
  + **不同的連接埠** – `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING` – 設定為 `RUNTIME_ERROR` 以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。

**有效值**
  + `RUNTIME_ERROR` – 擲回執行時間例外狀況。
  + `LOG_ERROR` – 記錄錯誤並繼續 （預設）。
  + `IGNORE_ERROR` – 忽略錯誤並繼續。

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

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