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

# 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`會自動在 中安裝所有套件。