使用適用於 Python 中間件的 X-Ray 開發套件之傳入請求 - AWS X-Ray
將中介軟體新增至應用程式 (Django)將中介軟體新增至應用程式 (Flask)將中介軟體新增至應用程式 (Bottle)手動檢測 Python 程式碼設定區段命名策略

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

使用適用於 Python 中間件的 X-Ray 開發套件之傳入請求

當您將中介軟體新增至應用程式並設定區段名稱時，Python 的 X-Ray SDK 會為每個取樣要求建立區段。此區段包括時間、方法，以及 HTTP 請求的處置方式。其他檢測會在此區段上建立子區段。

適用於 Python 的 X-Ray SDK 支援下列中間件來檢測傳入的 HTTP 請求：

  • Django

  • Flask

  • Bottle

注意

對於AWS Lambda函數，Lambda 會為每個取樣的請求建立區段。如需詳細資訊，請參閱 AWS Lambda 而且 AWS X-Ray。

如工作程序需在 Lambda 中檢測到的 Python 函數範例，請參閱。

針對指令碼或其他框架上的 Python 應用程式，您可以手動建立區段。

每個區段都有一個名稱，可在服務對應中識別您的應用程式。區段可以以靜態方式命名，也可以設定 SDK 根據傳入要求中的主機標頭動態命名該區段。動態命名可讓您根據要求中的網域名稱對追蹤進行分組，並在名稱與預期的模式不符時套用預設名稱 (例如，如果主機標頭是偽造的)。

轉寄的要求

如果負載平衡器或其他中介機構將要求轉寄至您的應用程式，X-Ray 會從要求中的X-Forwarded-For標頭取得用戶端 IP，而不是從 IP 封包中的來源 IP 取得。為轉寄的要求所記錄的用戶端 IP 可以偽造，因此不應該受信任。

轉送請求時，SDK 會在區段中設定一個額外的欄位來指出這一點。如果區段包含x_forwarded_for設定為的欄位true，則會從 HTTP 要求中的X-Forwarded-For標頭取得用戶端 IP。

中介軟體會使用 http 區塊為每個傳入的請求建立區段，其中包含以下資訊：

  • HTTP 方法-GET、POST、PUT、DELETE 等

  • [用戶端地址]-傳送請求的用戶端 IP 地址。

  • 回應碼 — 已完成要求的 HTTP 回應碼。

  • 時間 — 開始時間 (收到請求的時間) 和結束時間 (傳送回應的時間)。

  • 使用者代理程式 —user-agent 來自請求的。

  • 「內容長度」— 響應content-length中的內容。

將中介軟體新增至應用程式 (Django)

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

範例 settings.py-適用於蟒蛇中間件的 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 記錄器。

範例 settings.py-適用於蟒蛇應用程序的 X-Ray SDK
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 檔案中設定區段名稱。

範例 settings.py — 區段名稱
XRAY_RECORDER = {
    'AWS_XRAY_TRACING_NAME': 'My application',
    'PLUGINS': ('EC2Plugin',),
}

這告訴 X-Ray 記錄器以默認採樣率跟踪 Django 應用程序提供的請求。您可以在您的 Django 設定檔中設定記錄器來套用自訂抽樣規則或變更其他設定。

注意

由plugins於作為元組傳入，因此在指定單個插件,時請務必包含尾隨。例如：plugins = ('EC2Plugin',)

將中介軟體新增至應用程式 (Flask)

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

範例 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 應用程序提供的請求。您可以在程式碼中設定記錄器來套用自訂抽樣規則或變更其他設定。

將中介軟體新增至應用程式 (Bottle)

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

範例 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 應用程序提供的請求。您可以在程式碼中設定記錄器來套用自訂抽樣規則或變更其他設定。

手動檢測 Python 程式碼

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

範例 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()

設定區段命名策略

AWS X-Ray使用服務名稱來識別您的應用程式，並將其與應用程式使用的其他應用程式、資料庫、外部 API 和AWS資源區分開來。X-Ray SDK 為傳入要求產生區段時，會在區段的名稱欄位中記錄應用程式的服務名稱。

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

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

例如，您可能有一個應用程式向三個子網域提供要求 —www.example.comapi.example.com、和static.example.com。您可以將動態命名策略與模式搭配使用，*.example.com以識別具有不同名稱的每個子網域的區段，從而在服務對應上產生三個服務節點。如果您的應用程式收到的主機名稱與模式不相符的要求，您會在服務對應上看到第四個節點，其中包含您指定的後援名稱。

若要為所有請求區段使用相同的名稱，請如上一節所述，在設定記錄器時指定您應用程式的名稱。

動態命名策略可定義主機名稱應相符的模式，以及如果 HTTP 請求中的主機名稱不符合模式時要使用的預設名稱。若要在 Django 中動態命名區段，請將 DYNAMIC_NAMING 設定新增到您的 settings.py 檔案。

範例 settings.py-動態命名
XRAY_RECORDER = {
    'AUTO_INSTRUMENT': True,
    'AWS_XRAY_TRACING_NAME': 'My application',
    'DYNAMIC_NAMING': '*.example.com',
    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}

您可以在模式中使用 '*' 來比對任何字串，或是 '?' 來比對任何單一字元。針對 Flask，請在程式碼中設定記錄器。

範例 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 環境變數來覆寫您在程式碼中定義的預設服務名稱。