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

# AWS X-Ray 適用於 Python 的 SDK
<a name="xray-sdk-python"></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 開發套件是 Python Web 應用程式的程式庫，提供產生追蹤資料並將其傳送至 X-Ray 協助程式的類別和方法。追蹤資料包含應用程式所服務傳入 HTTP 請求的相關資訊，以及應用程式使用 AWS SDK、HTTP 用戶端或 SQL 資料庫連接器對下游服務進行的呼叫。您也可以手動建立區段，並將除錯資訊新增至註釋和中繼資料中。

您可以使用 `pip` 下載軟體開發套件。

```
$ pip install aws-xray-sdk
```

**注意**  
適用於 Python 的 X-Ray 開發套件是開放原始碼專案。您可以關注專案，並在 GitHub 上提交問題與提取 (pull) 請求：[github.com/aws/aws-xray-sdk-python](https://github.com/aws/aws-xray-sdk-python)

若您使用 Django 或 Flask，請從[將軟體開發套件中介軟體新增到您的應用程式](xray-sdk-python-middleware.md)開始，來追蹤傳入請求。中介軟體會為每個追蹤的請求建立[區段](xray-concepts.md#xray-concepts-segments)，並在傳送回應時完成區段。當區段開啟時，您可以使用軟體開發套件用戶端的方法，將資訊新增到區段，並建立子區段以追蹤下游呼叫。軟體開發套件也會在區段為開啟時自動記錄應用程式擲回的例外狀況。針對其他應用程式，您可以[手動建立區段](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual)。

對於經檢測應用程式或服務呼叫的 Lambda 函數，Lambda 會自動讀取[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)並追蹤取樣的請求。對於其他 函數，您可以[設定 Lambda](xray-services-lambda.md) 來取樣和追蹤傳入的請求。無論哪種情況，Lambda 都會建立客群並將其提供給 X-Ray 開發套件。

**注意**  
在 Lambda 上，X-Ray 開發套件是選用的。如果您未在函數中使用它，您的服務映射仍會包含 Lambda 服務的節點，以及每個 Lambda 函數的節點。透過新增 SDK，您可以檢測函數程式碼，將子區段新增至 Lambda 記錄的函數區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。

[工作程序](scorekeep-lambda.md#scorekeep-lambda-worker) 如需在 Lambda 中檢測的範例 Python 函數，請參閱 。

接著，使用適用於 Python 的 X-Ray 開發套件，透過[修補應用程式的程式庫](xray-sdk-python-patching.md)來檢測下游呼叫。軟體開發套件支援以下程式庫。

**支援的程式庫**
+ `[botocore](https://pypi.python.org/pypi/botocore)`， `[boto3](https://pypi.python.org/pypi/boto3)` – 檢測 適用於 Python (Boto) 的 AWS SDK 用戶端。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Instrument PynamoDB 的 Amazon DynamoDB 用戶端版本。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、 `[aioboto3](https://pypi.python.org/pypi/aioboto3)` – 檢測適用於 Python 用戶端的 SDK [非同步](https://docs.python.org/3/library/asyncio.html)整合版本。
+ `[requests](https://pypi.python.org/pypi/requests)`， `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – 檢測高階 HTTP 用戶端。
+ `[httplib](https://docs.python.org/2/library/httplib.html)`， [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – 檢測低階 HTTP 用戶端和使用它們的更高層級程式庫。
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` – 檢測 SQLite 用戶端。
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – 檢測 MySQL 用戶端。
+ `[pg8000](https://pypi.org/project/pg8000/)` – Instrument Pure-Python PostgreSQL 介面。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – Instrument PostgreSQL 資料庫轉接器。
+ `[pymongo](https://pypi.org/project/pymongo/)` – 檢測 MongoDB 用戶端。
+ `[pymysql](https://pypi.org/project/PyMySQL/)` – 檢測 MySQL 和 MariaDB 的 PyMySQL 型用戶端。 MariaDB

每當您的應用程式呼叫 AWS SQL 資料庫或其他 HTTP 服務時，開發套件會在子區段中記錄有關呼叫的資訊。 AWS 服務 而您在服務中存取的資源會在追蹤地圖上顯示為下游節點，協助您識別錯誤並調節個別連線的問題。

開始使用 SDK 之後，請透過[設定記錄器和中介軟體來](xray-sdk-python-configuration.md)自訂其行為。您可以新增外掛程式，以記錄執行應用程式所需的運算資源相關資料、定義抽樣規則以自訂抽樣行為，並設定日誌層級以在應用程式日誌中查看更多或更少的軟體開發套件資訊。

使用[註釋與中繼資料](xray-sdk-python-segment.md)，記錄應用程式所做的請求和工作等其他資訊。註釋是簡單的鍵/值對，系統會為其建立索引以用於[篩選條件表達式](xray-console-filters.md)，因此您可以搜尋包含特定資料的追蹤。中繼資料項目的限制性較低，可以記錄整個物件和陣列，任何可以序列化為 JSON 的項目。

**標註與中繼資料**  
註釋和中繼資料是您使用 X-Ray SDK 新增至客群的任意文字。註釋會編製索引，以便與篩選條件表達式搭配使用。中繼資料不會編製索引，但可以使用 X-Ray 主控台或 API 在原始區段中檢視。您授予 X-Ray 讀取存取權的任何人都可以檢視此資料。

當程式碼中有很多經過檢測的用戶端時，單一請求區段可能包含大量子區段，每個使用經檢測用戶端進行的呼叫都有一個子區段。您可以將用戶端呼叫包裝在[自訂子區段](xray-sdk-python-subsegments.md)中，以組織和群組子區段。您可以為整個函數或一部分的程式碼建立自訂子區段。您接著可以在子區段上記錄中繼資料及標註，而非將所有項目寫入父區段。

如需 SDK 類別和方法的參考文件，請參閱[AWS X-Ray 適用於 Python 的 SDK API 參考](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference)。

## 要求
<a name="xray-sdk-python-requirements"></a>

適用於 Python 的 X-Ray 開發套件支援下列語言和程式庫版本。
+ **Python** – 2.7、3.4 和更新版本
+ **Django** – 1.10 及更新版本
+ **Flask** – 0.10 及更新版本
+ **aiohttp** – 2.3.0 及更新版本
+ **適用於 Python (Boto) 的 AWS SDK** – 1.4.0 及更新版本
+ **botocore** – 1.5.0 及更新版本
+ **enum** – 0.4.7 及更新版本，適用於 Python 3.4.0 及更新版本
+ **jsonpickle** – 1.0.0 及更新版本
+ **setuptools** – 40.6.3 和更新版本
+ **wrapt** – 1.11.0 及更新版本

## 相依性管理
<a name="xray-sdk-python-dependencies"></a>

適用於 Python 的 X-Ray 開發套件可從 取得`pip`。
+ **套件** – `aws-xray-sdk`

在您的 `requirements.txt` 檔案中將軟體開發套件新增為依存項目。

**Example requirements.txt**  

```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```

如果您使用 Elastic Beanstalk 部署應用程式，Elastic Beanstalk `requirements.txt`會自動在 中安裝所有套件。

# 設定適用於 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` – 忽略錯誤並繼續。

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

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

# 使用適用於 Python 的 X-Ray 開發套件中介軟體追蹤傳入請求
<a name="xray-sdk-python-middleware"></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 開發套件會為每個取樣請求建立區段。此區段包括時間、方法，以及 HTTP 請求的處置方式。其他檢測會在此區段上建立子區段。

適用於 Python 的 X-Ray 開發套件支援下列中介軟體，以檢測傳入的 HTTP 請求：
+ Django
+ Flask
+ Bottle

**注意**  
對於 AWS Lambda 函數，Lambda 會為每個取樣請求建立區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。

[工作程序](scorekeep-lambda.md#scorekeep-lambda-worker) 如需在 Lambda 中檢測的範例 Python 函數，請參閱 。

針對指令碼或其他框架上的 Python 應用程式，您可以[手動建立區段](#xray-sdk-python-middleware-manual)。

每個區段都有一個名稱，可在服務映射中識別您的應用程式。區段可以靜態命名，或者您可以設定 SDK 根據傳入請求中的主機標頭動態命名。動態命名可讓您根據請求中的網域名稱來分組追蹤，並在名稱不符合預期模式時套用預設名稱 （例如，如果主機標頭是偽造的）。

**轉送的請求**  
如果負載平衡器或其他中介裝置轉送請求到您的應用程式，X-Ray 會從請求中的 `X-Forwarded-For`標頭取得用戶端 IP，而不是從 IP 封包中的來源 IP 取得用戶端 IP。為轉送請求記錄的用戶端 IP 可能是偽造的，因此不應受信任。

轉送請求時，開發套件會在區段中設定額外的欄位來表示這一點。如果區段包含`x_forwarded_for`設為 的欄位`true`，用戶端 IP 會從 HTTP 請求中的 `X-Forwarded-For`標頭取得。

中介軟體會使用 `http` 區塊為每個傳入的請求建立區段，其中包含以下資訊：
+ **HTTP 方法** – GET、POST、PUT、DELETE 等。
+ **用戶端地址** – 傳送請求之用戶端的 IP 地址。
+ **回應碼** – 已完成請求的 HTTP 回應碼。
+ **時間** – 開始時間 （收到請求的時間） 和結束時間 （傳送回應的時間）。
+ **使用者代理程式** — 來自請求`user-agent`的 。
+ **內容長度** — `content-length`來自回應的 。

**Topics**
+ [

## 將中介軟體新增至應用程式 (Django)
](#xray-sdk-python-adding-middleware-django)
+ [

## 將中介軟體新增至應用程式 (Flask)
](#xray-sdk-python-adding-middleware-flask)
+ [

## 將中介軟體新增至應用程式 (Bottle)
](#xray-sdk-python-adding-middleware-bottle)
+ [

## 手動檢測 Python 程式碼
](#xray-sdk-python-middleware-manual)
+ [

## 設定區段命名策略
](#xray-sdk-python-middleware-naming)

## 將中介軟體新增至應用程式 (Django)
<a name="xray-sdk-python-adding-middleware-django"></a>

將中介軟體新增至您 `settings.py` 檔案中的 `MIDDLEWARE` 清單。X-Ray 中介軟體應為您 `settings.py` 檔案中的第一行，確保會記錄在其他中介軟體中失敗的請求。

**Example settings.py - 適用於 Python 中介軟體的 X-Ray SDK**  

```
MIDDLEWARE = [
    'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware'
]
```

將 X-Ray SDK Django 應用程式新增至`settings.py`檔案中的`INSTALLED_APPS`清單。這將允許在您的應用程式啟動期間設定 X-Ray 記錄器。

**Example settings.py - X-Ray SDK for Python Django 應用程式**  

```
INSTALLED_APPS = [
    'aws_xray_sdk.ext.django',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]
```

在您的 [`settings.py` 檔案](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)中設定區段名稱。

**Example settings.py – 區段名稱**  

```
XRAY_RECORDER = {
    'AWS_XRAY_TRACING_NAME': 'My application',
    'PLUGINS': ('EC2Plugin',),
}
```

這可讓 X-Ray 記錄器以預設取樣率追蹤 Django 應用程式提供的請求。您可以[在您的 Django 設定檔中設定記錄器](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)來套用自訂抽樣規則或變更其他設定。

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

## 將中介軟體新增至應用程式 (Flask)
<a name="xray-sdk-python-adding-middleware-flask"></a>

若要檢測您的 Flask 應用程式，請先在 `xray_recorder` 上設定區段名稱。然後，使用 `XRayMiddleware` 函數來在程式碼中修補您的 Flask 應用程式。

**Example app.py**  

```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware

app = Flask(__name__)

xray_recorder.configure(service='My application')
XRayMiddleware(app, xray_recorder)
```

這會通知 X-Ray 記錄器以預設取樣率追蹤 Flask 應用程式提供的請求。您可以[在程式碼中設定記錄器](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)來套用自訂抽樣規則或變更其他設定。

## 將中介軟體新增至應用程式 (Bottle)
<a name="xray-sdk-python-adding-middleware-bottle"></a>

若要檢測您的 Bottle 應用程式，請先在 `xray_recorder` 上設定區段名稱。然後，使用 `XRayMiddleware` 函數來在程式碼中修補您的 Bottle 應用程式。

**Example app.py**  

```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
 
app = Bottle()
 
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))
```

這會通知 X-Ray 記錄器以預設取樣率追蹤 Bottle 應用程式提供的請求。您可以[在程式碼中設定記錄器](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)來套用自訂抽樣規則或變更其他設定。

## 手動檢測 Python 程式碼
<a name="xray-sdk-python-middleware-manual"></a>

若您並未使用 Django 或 Flask，您可以手動建立區段。您可以為每個傳入請求建立區段，或在修補的 HTTP 或 AWS SDK 用戶端周圍建立區段，以提供記錄器新增子區段的內容。

**Example https：//main.py – 手動檢測**  

```
from aws_xray_sdk.core import xray_recorder

# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')

# Add metadata and annotations
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')

# Close the subsegment and segment
xray_recorder.end_subsegment()
xray_recorder.end_segment()
```

## 設定區段命名策略
<a name="xray-sdk-python-middleware-naming"></a>

AWS X-Ray 使用*服務名稱*來識別您的應用程式，並將其與您的應用程式使用的其他應用程式、資料庫、外部 APIs AWS 和資源區分開來。當 X-Ray SDK 為傳入請求產生區段時，它會在區段的名稱欄位中記錄應用程式的服務[名稱](xray-api-segmentdocuments.md#api-segmentdocuments-fields)。

X-Ray SDK 可以在 HTTP 請求標頭中的主機名稱之後命名區段。不過，此標頭可以偽造，這可能會導致服務映射中出現非預期的節點。若要防止 SDK 因具有偽造主機標頭的請求而不正確地命名區段，您必須指定傳入請求的預設名稱。

如果您的應用程式為多個網域提供請求，您可以將 SDK 設定為使用動態命名策略，以在區段名稱中反映這一點。動態命名策略可讓軟體開發套件針對符合預期模式的請求使用主機名稱，並將預設名稱套用至不符合的請求。

例如，您可能有一個應用程式向三個子網域提供請求：`www.example.com`、 `api.example.com`和 `static.example.com`。您可以使用動態命名策略搭配 模式`*.example.com`，以不同名稱識別每個子網域的區段，在服務映射上產生三個服務節點。如果您的應用程式收到主機名稱不符合模式的請求，您會在服務映射上看到具有您指定之備用名稱的第四個節點。

若要為所有請求區段使用相同的名稱，請如[上一節](#xray-sdk-python-adding-middleware-django)所述，在設定記錄器時指定您應用程式的名稱。

動態命名策略可定義主機名稱應相符的模式，以及如果 HTTP 請求中的主機名稱不符合模式時要使用的預設名稱。若要在 Django 中動態命名區段，請將 `DYNAMIC_NAMING` 設定新增到您的 [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) 檔案。

**Example settings.py – 動態命名**  

```
XRAY_RECORDER = {
    'AUTO_INSTRUMENT': True,
    'AWS_XRAY_TRACING_NAME': 'My application',
    'DYNAMIC_NAMING': '*.example.com',
    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```

您可以在模式中使用 '\$1' 來比對任何字串，或是 '?' 來比對任何單一字元。針對 Flask，請[在程式碼中設定記錄器](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)。

**Example main.py – 區段名稱**  

```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```

**注意**  
您可以使用 `AWS_XRAY_TRACING_NAME` [環境變數](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars)來覆寫您在程式碼中定義的預設服務名稱。

# 修補程式庫來檢測下游呼叫
<a name="xray-sdk-python-patching"></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 開發套件來修補應用程式使用的程式庫。適用於 Python 的 X-Ray 開發套件可以修補下列程式庫。

**支援的程式庫**
+ `[botocore](https://pypi.python.org/pypi/botocore)`， `[boto3](https://pypi.python.org/pypi/boto3)` – 檢測 適用於 Python (Boto) 的 AWS SDK 用戶端。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Instrument PynamoDB 的 Amazon DynamoDB 用戶端版本。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、 `[aioboto3](https://pypi.python.org/pypi/aioboto3)` – 檢測適用於 Python 用戶端的 SDK [非同步](https://docs.python.org/3/library/asyncio.html)整合版本。
+ `[requests](https://pypi.python.org/pypi/requests)`， `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – 檢測高階 HTTP 用戶端。
+ `[httplib](https://docs.python.org/2/library/httplib.html)`、 [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – 檢測低階 HTTP 用戶端和使用它們的更高層級程式庫。
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` – 檢測 SQLite 用戶端。
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – 檢測 MySQL 用戶端。
+ `[pg8000](https://pypi.org/project/pg8000/)` – Instrument Pure-Python PostgreSQL 介面。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – Instrument PostgreSQL 資料庫轉接器。
+ `[pymongo](https://pypi.org/project/pymongo/)` – Instrument MongoDB 用戶端。
+ `[pymysql](https://pypi.org/project/PyMySQL/)` – 檢測 MySQL 和 MariaDB 的 PyMySQL 型用戶端。 MariaDB

當您使用修補的程式庫時，適用於 Python 的 X-Ray 開發套件會為呼叫建立子區段，並記錄來自請求和回應的資訊。區段必須透過軟體開發套件中介軟體或 AWS Lambda供軟體開發套件使用，以建立子區段。

**注意**  
若您使用 SQLAlchemy ORM，您可以透過匯入 SQLAlchemy 工作階段和查詢類別的軟體開發套件版本，來檢測您的 SQL 查詢。如需說明，請參閱[使用 SQLAlchemy ORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm)。

若要修補所有可用程式庫，請使用 `aws_xray_sdk.core` 中的 `patch_all` 函數。有些程式庫 (例如 `httplib` 和 `urllib`) 可能需要呼叫 `patch_all(double_patch=True)` 以啟用雙重修補。

**Example main.py – 修補所有支援的程式庫**  

```
import boto3
import botocore
import requests
import sqlite3

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

patch_all()
```

若要修補單一程式庫，請以該程式庫名稱的元組來呼叫 `patch`。若要執行這個作業，您將需要提供單一個元素清單。

**Example main.py – 修補特定程式庫**  

```
import boto3
import botocore
import requests
import mysql-connector-python

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch

libraries = (['botocore'])
patch(libraries)
```

**注意**  
在某些情況下，您用來修補程式庫的鍵會與程式庫名稱不相符。有些鍵會做為一或多個程式庫的別名。  
`httplib`–`[httplib](https://docs.python.org/2/library/httplib.html)` 和 [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`

## 追蹤非同步工作的內容
<a name="xray-sdk-python-patching-async"></a>

對於`asyncio`整合式程式庫，或為[非同步函數建立子區段](xray-sdk-python-subsegments.md)，您還必須使用非同步內容設定適用於 Python 的 X-Ray 開發套件。匯入 `AsyncContext`類別，並將其執行個體傳遞至 X-Ray 記錄器。

**注意**  
Web 架構支援程式庫，例如 AIOHTTP，將不會經由 `aws_xray_sdk.core.patcher` 模組獲得處理。它們不會出現在支援程式庫的 `patcher` 目錄中。

**Example main.py – 修補程式 aioboto3**  

```
import asyncio
import aioboto3
import requests

from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch

libraries = (['aioboto3'])
patch(libraries)
```

# 使用適用於 Python 的 X-Ray AWS 開發套件追蹤 SDK 呼叫
<a name="xray-sdk-python-awssdkclients"></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)。

當您的應用程式呼叫 AWS 服務 來存放資料、寫入佇列或傳送通知時，適用於 Python 的 X-Ray 開發套件會在[子區段](xray-sdk-python-subsegments.md)中追蹤下游的呼叫。您在這些服務中存取的追蹤 AWS 服務 和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。

當您[修補程式`botocore`庫](xray-sdk-python-patching.md)時，適用於 Python 的 X-Ray 開發套件會自動檢測所有 AWS SDK 用戶端。您無法檢測個別用戶端。

對於所有 服務，您可以在 X-Ray 主控台中查看名為 的 API 名稱。對於服務子集，X-Ray SDK 會將資訊新增至區段，以在服務映射中提供更精細的服務。

例如，當您使用經檢測的 DynamoDB 用戶端進行呼叫時，軟體開發套件會將資料表名稱新增至以資料表為目標的呼叫區段。在 主控台中，每個資料表會在服務映射中顯示為個別節點，並針對非資料表目標的呼叫使用一般 DynamoDB 節點。

**Example 呼叫 DynamoDB 以儲存項目的子區段**  

```
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}
```

您存取具名資源時，對以下服務的呼叫會在服務地圖中建立額外節點。未針對特定資源的呼叫，則會建立服務的一般節點。
+ **Amazon DynamoDB** – 資料表名稱
+ **Amazon Simple Storage Service** – 儲存貯體和金鑰名稱
+ **Amazon Simple Queue Service** – 佇列名稱

# 使用適用於 Python 的 X-Ray 開發套件追蹤對下游 HTTP Web 服務的呼叫
<a name="xray-sdk-python-httpclients"></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)。

當您的應用程式呼叫微服務或公有 HTTP APIs，您可以使用適用於 Python 的 X-Ray 開發套件來檢測這些呼叫，並將 API 做為下游服務新增至服務圖表。

若要檢測 HTTP 用戶端，請[修補您用來進行傳出呼叫的程式庫](xray-sdk-python-patching.md)。若您使用 `requests` 或 Python 內建的 HTTP 用戶端，只需進行這些作業。針對 `aiohttp`，請同時使用[非同步內容](xray-sdk-python-patching.md#xray-sdk-python-patching-async)設定記錄器。

若您使用 `aiohttp` 3 的用戶端 API，您也需要使用軟體開發套件提供的追蹤組態執行個體設定 `ClientSession` 的部分。

**Example [`aiohttp` 3 用戶端 API](https://github.com/aws/aws-xray-sdk-python#trace-aiohttp-client-requests)**  

```
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config

async def foo():
    trace_config = aws_xray_trace_config()
    async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
        async with session.get(url) as resp
            await resp.read()
```

當您檢測對下游 Web API 的呼叫時，適用於 Python 的 X-Ray 開發套件會記錄子區段，其中包含 HTTP 請求和回應的相關資訊。X-Ray 使用子區段來產生遠端 API 的推斷區段。

**Example 下游 HTTP 呼叫的子區段**  

```
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
```

**Example 下游 HTTP 呼叫的推斷區段**  

```
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}
```

# 使用適用於 Python 的 X-Ray 開發套件產生自訂子區段
<a name="xray-sdk-python-subsegments"></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)。

子區段會延伸追蹤的[區段](xray-concepts.md#xray-concepts-segments)，其中包含為了處理請求而完成之工作的詳細資訊。每次您與經檢測的用戶端進行呼叫時，X-Ray 開發套件都會記錄子區段中產生的資訊。您可以建立其他子區段來將其他子區段分組、測量程式碼區段的效能，或記錄註釋和中繼資料。

若要管理子區段，請使用 `begin_subsegment` 和 `end_subsegment` 方法。

**Example main.py – 自訂子區段**  

```
from aws_xray_sdk.core import xray_recorder

subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```

若要建立同步函數的子區段，請使用 `@xray_recorder.capture` 裝飾項目。您可以將子區段的名稱傳遞給擷取函數，或是不傳遞它來使用函數名稱。

**Example main.py – 函數子區段**  

```
from aws_xray_sdk.core import xray_recorder

@xray_recorder.capture('## create_user')
def create_user():
...
```

針對非同步函數，請使用 `@xray_recorder.capture_async` 裝飾項目，並將非同步內容傳遞給記錄器。

**Example main.py – 非同步函數子區段**  

```
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())

@xray_recorder.capture_async('## create_user')
async def create_user():
    ...

async def main():
    await myfunc()
```

當您在區段或其他子區段中建立子區段時，適用於 Python 的 X-Ray 開發套件會為其產生 ID，並記錄開始時間和結束時間。

**Example 使用中繼資料的子區段**  

```
"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
```

# 使用適用於 Python 的 X-Ray 開發套件將註釋和中繼資料新增至區段
<a name="xray-sdk-python-segment"></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)。

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

**註釋**是具有字串、數字或布林值的鍵值對。註釋會編製索引，以便與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。

**中繼資料**是索引鍵/值對，可以具有任何類型的值，包括物件和清單，但不會編製索引以與篩選條件表達式搭配使用。使用中繼資料記錄您希望儲存在追蹤中的其他資料，但不需要搭配搜尋使用。

除了註釋和中繼資料，您也可以在區段上[記錄使用者 ID 字串](#xray-sdk-python-segment-userid)。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。

**Topics**
+ [

## 使用適用於 Python 的 X-Ray 開發套件記錄註釋
](#xray-sdk-python-segment-annotations)
+ [

## 使用適用於 Python 的 X-Ray 開發套件記錄中繼資料
](#xray-sdk-python-segment-metadata)
+ [

## 使用適用於 Python 的 X-Ray 開發套件記錄使用者 IDs
](#xray-sdk-python-segment-userid)

## 使用適用於 Python 的 X-Ray 開發套件記錄註釋
<a name="xray-sdk-python-segment-annotations"></a>

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

**註釋要求**
+ **金鑰** – 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()
   ```

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

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

   下列範例顯示如何使用包含點的`putAnnotation`字串索引鍵和布林值、數字或字串值來呼叫 。

   ```
   document.putAnnotation("testkey.test", "my value");
   ```

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

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

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

若要尋找具有具有特定值註釋的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `annotation[key]`關鍵字。

## 使用適用於 Python 的 X-Ray 開發套件記錄中繼資料
<a name="xray-sdk-python-segment-metadata"></a>

**警告**  
請勿將具有循環參考的物件新增為適用於 Python 的 X-Ray 開發套件中的中繼資料值。這些物件無法序列化為 JSON，且可能在 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()
   ```

1. 使用字串鍵、布林值、數字、字串或物件值，以及字串命名空間，呼叫 `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` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。

## 使用適用於 Python 的 X-Ray 開發套件記錄使用者 IDs
<a name="xray-sdk-python-segment-userid"></a>

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

**記錄使用者 ID**

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

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

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

   ```
   document.set_user("U12345");
   ```

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

若要尋找使用者 ID 的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `user`關鍵字。

# 檢測部署在無伺服器環境中的 Web 框架
<a name="xray-sdk-python-serverless"></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 的 AWS X-Ray 開發套件支援檢測部署在無伺服器應用程式中的 Web 架構。無伺服器解決方案是雲端原生架構，能讓您將更多的操作責任轉移到 AWS，提高您的敏捷度和創新能力。

無伺服器架構是一種軟體應用程式模型，可讓您建置和執行應用程式和服務，而完全不用考慮伺服器。這種做法可免除基礎設施管理工作，例如伺服器或叢集佈建、修補、作業系統維護和容量佈建。您可以為幾乎任何應用程式類型或後端服務建立無伺服器解決方案，並為您包辦執行和擴展高可用性應用程式所需的一切工作。

本教學課程說明如何自動 AWS X-Ray 檢測部署到無伺服器環境的 Web 架構，例如 Flask 或 Django。應用程式的 X-Ray 檢測可讓您檢視從 Amazon API Gateway 透過 AWS Lambda 函數進行的所有下游呼叫，以及應用程式發出的外撥呼叫。

適用於 Python 的 X-Ray 開發套件支援下列 Python 應用程式架構：
+ Flask 版本 0.8 或更新版本
+ Django 版本 1.0 或更新版本

本教學課程開發了部署到 Lambda 並由 API Gateway 調用的範例無伺服器應用程式。本教學課程使用 Zappa 自動將應用程式部署至 Lambda，並設定 API Gateway 端點。

## 先決條件
<a name="xray-sdk-python-serverless-prereqs"></a>
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html) – 2.7 或 3.6 版。
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) – 確認您的 AWS CLI 已使用 AWS 區域 您要部署應用程式的 帳戶設定。
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)

## 步驟 1：建立環境
<a name="xray-sdk-python-serverless-environment"></a>

在此步驟中，您將建立使用 `virtualenv` 來主控應用程式的虛擬環境。

1. 使用 AWS CLI為應用程式建立目錄。然後，切換至新目錄。

   ```
   mkdir serverless_application
   cd serverless_application
   ```

1. 接下來，在您的新目錄中建立虛擬環境。使用下列命令，將其啟動。

   ```
   # Create our virtual environment
   virtualenv serverless_env
   
   # Activate it
   source serverless_env/bin/activate
   ```

1. 將 X-Ray、Flask、Zappa 和請求程式庫安裝到您的環境。

   ```
   # Install X-Ray, Flask, Zappa, and Requests into your environment
   pip install aws-xray-sdk flask zappa requests
   ```

1. 將應用程式程式碼新增到 `serverless_application` 目錄。在這個範例中，我們可以建置出 Flasks 的 [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) 範例。

   在 `serverless_application` 目錄中，建立名為 `my_app.py` 的檔案。然後，使用文字編輯器來新增下列命令。這個應用程式會檢測請求程式庫、修補 Flask 應用程式的中介軟體，並開啟端點 `'/'`。

   ```
   # Import the X-Ray modules
   from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
   from aws_xray_sdk.core import patcher, xray_recorder
   from flask import Flask
   import requests
   
   # Patch the requests module to enable automatic instrumentation
   patcher.patch(('requests',))
   
   app = Flask(__name__)
   
   # Configure the X-Ray recorder to generate segments with our service name
   xray_recorder.configure(service='My First Serverless App')
   
   # Instrument the Flask application
   XRayMiddleware(app, xray_recorder)
    
   @app.route('/')
   def hello_world():
       resp = requests.get("https://aws.amazon.com")
       return 'Hello, World: %s' % resp.url
   ```

## 步驟 2：建立和部署 Zappa 環境
<a name="xray-sdk-python-serverless-zappa"></a>

在此步驟中，您將使用 Zappa 自動設定 API Gateway 端點，然後部署到 Lambda。

1. 從 `serverless_application` 目錄當中起始 Zappa。在這個範例中，我們使用的是預設設定，但如果您有自訂偏好設定，則 Zappa 會顯示組態指示。

   ```
   zappa init
   ```

   ```
   What do you want to call this environment (default 'dev'): dev
   ...
   What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
   ...
   ...
   It looks like this is a Flask application.
   What's the modular path to your app's function?
   This will likely be something like 'your_module.app'.
   We discovered: my_app.app
   Where is your app's function? (default 'my_app.app'): my_app.app
   ...
   Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
   ```

1. 啟用 X-Ray。開啟 `zappa_settings.json` 檔案，並確認其類似此範例。

   ```
   {
       "dev": {
           "app_function": "my_app.app",
           "aws_region": "us-west-2",
           "profile_name": "default",
           "project_name": "serverless-exam",
           "runtime": "python2.7",
           "s3_bucket": "zappa-*********"
       }
   }
   ```

1. 將 `"xray_tracing": true` 新增做為組態檔的項目：

   ```
   {
       "dev": {
           "app_function": "my_app.app",
           "aws_region": "us-west-2",
           "profile_name": "default",
           "project_name": "serverless-exam",
           "runtime": "python2.7",
           "s3_bucket": "zappa-*********",
           "xray_tracing": true
       }
   }
   ```

1. 部署應用程式。這會自動設定 API Gateway 端點，並將您的程式碼上傳至 Lambda。

   ```
   zappa deploy
   ```

   ```
   ...
   Deploying API Gateway..
   Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
   ```

## 步驟 3：啟用 API Gateway 的 X-Ray 追蹤
<a name="xray-sdk-python-serverless-xray"></a>

在此步驟中，您將與 API Gateway 主控台互動，以啟用 X-Ray 追蹤。

1. 登入 AWS 管理主控台 並開啟 API Gateway 主控台，網址為 https：//[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/)。

1. 尋找新產生的 API。該項目看起來應該會類似 `serverless-exam-dev`。

1. 選擇 **Stages** (階段)。

1. 選擇您的部署階段名稱。預設值為 `dev`。

1. 在 **Logs/Tracing (日誌/追蹤)** 標籤中，選取 **Enable X-Ray Tracing (啟用 X-Ray 追蹤)** 方塊。

1. 選擇 **Save Changes** (儲存變更)。

1. 在您的瀏覽器中存取端點。如果您使用的是 `Hello World` 應用程式範例，這時應該顯示如下。

   ```
   "Hello, World: https://aws.amazon.com/"
   ```

## 步驟 4：檢視已建立的追蹤
<a name="xray-sdk-python-serverless-trace"></a>

在此步驟中，您將與 X-Ray 主控台互動，以檢視範例應用程式建立的追蹤。如需追蹤分析的詳細演練，請參閱[檢視服務映射](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)。

1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 的 X-Ray 主控台。

1. 檢視 API Gateway、Lambda 函數和 Lambda 容器所產生的區段。

1. 在 Lambda 函數區段下，檢視名為 的子區段`My First Serverless App`。它的後面是一個名為 `https://aws.amazon.com` 的第二個子區段。

1. 在初始化期間，Lambda 也可能產生名為 的第三個子區段`initialization`。

![\[追蹤區段檢視。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/serverless-traceView.png)


![\[服務圖表檢視。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/serverless-serviceView.png)


## 步驟 5：清除
<a name="xray-sdk-python-serverless-cleanup"></a>

務必終止您不再使用的資源，避免累積超出預期的費用。在此教學示範中，像是 Zappa 等工具會簡化無伺服器解決方案的重新部署。

若要從 Lambda、API Gateway 和 Amazon S3 中移除您的應用程式，請使用 在專案目錄中執行下列命令 AWS CLI。

```
zappa undeploy dev
```

## 後續步驟
<a name="xray-sdk-python-serverless-next"></a>

透過新增 AWS 用戶端並使用 X-Ray 檢測，將更多功能新增至您的應用程式。進一步了解 Serverless [on 的無 AWS](https://aws.amazon.com/serverless)伺服器運算選項。