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

# 使用適用於 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)來覆寫您在程式碼中定義的預設服務名稱。