使用X-Ray SDK for Python中间件跟踪传入请求 - AWS X-Ray
将中间件添加到应用程序 (Django)将中间件添加到应用程序 (Flask)将中间件添加到应用程序 (Bottle)手动分析 Python 代码配置分段命名策略
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用X-Ray SDK for Python中间件跟踪传入请求

在您将中间件添加到应用程序并配置分段名称时，X-Ray SDK for Python会为每个采样请求创建一个分段。此分段包括 HTTP 请求的计时、方法和处置。其他分析会在此分段上创建子分段。

X-Ray SDK for Python 支持以下中间件来分析传入的 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)

将中间件添加到 MIDDLEWARE 文件中的 settings.py 列表。X-Ray 中间件应位于 settings.py 文件中的第一行，以确保在其他中间件失败的请求得到记录。

例 settings.py - X-Ray SDK for Python中间件

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-RaySDKDjango应用程序添加到 INSTALLED_APPS 列表中, settings.py 文件。这将允许在应用程序启动期间配置X射线记录器。

例 设置.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 文件中配置分段名称。

例 settings.py – 分段名称

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

这告知 X-Ray 记录器使用默认采样率跟踪您的 Django 应用程序处理的请求。您可以在您的 Django 设置文件中配置记录器，以便应用自定义采样规则或更改其他设置。

将中间件添加到应用程序 (Flask)

要安装您的“摇瓶”应用程序,首先在 xray_recorder。然后,使用 XRayMiddleware 功能,以修补代码中的摇瓶应用程序。

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

要对“试剂瓶”应用程序进行仪表设置,首先在上配置段名称 xray_recorder。然后,使用 XRayMiddleware 功能以修补代码中的试剂瓶应用程序。

例 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 开发工具包客户端创建分段以便为记录器提供上下文来添加子分段。

例 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 开发工具包为传入请求生成分段时，它将在分段的名称字段中记录您的应用程序的服务名称。

X-Ray 开发工具包可以 HTTP 请求标头中的主机名为分段命名。但是，此标头可伪造，这可能导致您的服务地图中出现意外节点。为防止对伪造的主机标头的请求导致 SDK 不正确地命名分段，您必须为传入请求指定默认名称。

如果您的应用程序处理对多个域的请求，您可以将开发工具包配置为使用动态命名策略以在分段名称中反映此行为。通过动态命名策略，开发工具包可将主机名用于与预期模式匹配的请求，并将默认名称应用于与预期模式不匹配的请求。

例如，您可能有一个处理对三个子域（www.example.com、api.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 环境变量覆盖您在代码中定义的默认服务名称。