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

# Amazon X-Ray Python 软件开发工具包
X-Ray SDK for Python

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

X-Ray SDK for Python 是一个面向 Python Web 应用程序的库，该库提供用于生成跟踪数据并将其发送到 X-Ray 进程守护程序的类和方法。跟踪数据包括有关应用程序处理的传入 HTTP 请求的信息，以及应用程序使用 Amazon SDK、HTTP 客户端或 SQL 数据库连接器对下游服务进行的调用的信息。您还可以手动创建分段并在注释和元数据中添加调试信息。

可以使用 `pip` 下载 SDK。

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

**注意**  
X-Ray SDK for Python 是一个开源项目。你可以关注该项目并在 [github 上 GitHub提交议题和拉取请求。 com/aws/aws](https://github.com/aws/aws-xray-sdk-python)-xray-sdk-python

如果您使用的是 Django 或 Flask，请首先[将 SDK 中间件添加到您的应用程序](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 函数的节点。可通过添加该开发工具包检测函数代码，将子分段添加到 Lambda 记录的函数分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。

有关在 Lambda 中检测过的示例 Python 函数，请参阅[工作线程](scorekeep-lambda.md#scorekeep-lambda-worker)。

接下来，通过[修补应用程序库](xray-sdk-python-patching.md)，使用 X-Ray SDK for Python 检测下游调用。该 SDK 支持以下库。

**支持的库**
+ `[botocore](https://pypi.python.org/pypi/botocore)`，`[boto3](https://pypi.python.org/pypi/boto3)`— 仪器 Amazon SDK for Python (Boto) 客户。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` - 检测 Amazon DynamoDB 客户端的 PynamoDB 版本。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、`[aioboto3](https://pypi.python.org/pypi/aioboto3)` - 检测 SDK for Python 客户端的 [asyncio](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/)` - 检测 Pure-Python PostgreSQL 接口。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` - 检测 PostgreSQL 数据库适配器。
+ `[pymongo](https://pypi.org/project/pymongo/)` - 检测 MongoDB 客户端。
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— 针对 My PyMy SQL 和 MariaDB 的基于 SQL 的客户端。

每当您的应用程序调用 SQL 数据库或其他 HTTP 服务时，SDK 都会在子分段中记录有关该调用的信息。 Amazon Amazon Web Services 服务 您在服务中访问的资源将作为下游节点显示在跟踪地图上，以帮助您识别各个连接上的错误和限制问题。

在开始使用 SDK 后，通过[配置记录器和中间件](xray-sdk-python-configuration.md)来自定义其行为。您可以添加插件来记录有关应用程序上运行的计算资源的数据，通过定义采样规则来自定义采样行为，设置日志级别以在应用程序日志中查看来自开发工具包的更多或更少的信息。

记录有关请求以及应用程序在[注释和元数据](xray-sdk-python-segment.md)中所做的工作的其他信息。注释是简单的键值对，已为这些键值对编制索引以用于[筛选条件表达式](xray-console-filters.md)，以便您能够搜索包含特定数据的跟踪。元数据条目的限制性较低，并且可以记录整个对象和数组 - 可序列化为 JSON 的任何项目。

**注释和元数据**  
注释和元数据是您使用 X-Ray 开发工具包添加到分段的任意文本。系统会对注释编制索引，以便与筛选表达式一起使用。元数据未编制索引，但可以使用 X-Ray 控制台或 API 在原始分段中查看。您授予 X-Ray 读取权限的任何人都可以查看这些数据。

当代码中具有大量检测的客户端时，一个请求分段可包含大量子分段，检测的客户端发起的每个调用均对应一个子分段。您可以通过将客户端调用包含在[自定义子分段](xray-sdk-python-subsegments.md)中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段。然后，您可以在子分段上记录元数据和注释，而不必在父分段上写入所有内容。

有关 SDK 的类和方法的参考文档，请参阅 [Amazon X-Ray SDK for Python API 参考](https://docs.amazonaws.cn/xray-sdk-for-python/latest/reference)。

## 要求


X-Ray SDK for Python 支持以下语言和库版本。
+ **Python** - 2.7、3.4 和更新版本
+ **Django** - 1.10 和更新版本
+ **Flask** - 0.10 和更新版本
+ **aiohttp** - 2.3.0 和更新版本
+ **Amazon SDK for Python (Boto)** - 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 和更新版本

## 依赖关系管理


可从 `pip` 获得 X-Ray SDK for Python。
+ **程序包** - `aws-xray-sdk`

在您的 `requirements.txt` 文件中添加 SDK 作为依赖项。

**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 开发工具包
配置

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/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)

## 服务插件


`plugins` 用于记录有关托管应用程序的服务的信息。

**插件**
+ Amazon EC2 — `EC2Plugin` 添加实例 ID、可用区和 CloudWatch 日志组。
+ Elastic Beanstalk - `ElasticBeanstalkPlugin` 添加环境名称、版本标签和部署 ID。
+ Amazon ECS — `ECSPlugin` 添加容器 ID。

![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.amazonaws.cn/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` 字段。这表示运行您的应用程序的 Amazon 资源类型。当您使用多个插件时，SDK 使用以下解析顺序来确定来源： ElasticBeanstalk > EKS > ECS > EC2。

## 采样规则


该 SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跟踪每秒的第一个请求，以及所有将跟踪发送到 X-Ray 的服务的任何其他请求的百分之五。[在 X-Ray 控制台中创建其他规则](xray-console-sampling.md)以自定义为每个应用程序记录的数据量。

该 SDK 按照定义的顺序应用自定义规则。如果请求与多个自定义规则匹配，则 SDK 仅应用第一条规则。

**注意**  
如果 SDK 无法访问 X-Ray 来获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求以及每个主机所有其他请求的百分之五。如果主机无权调用采样，或者无法连接到 X-Ray 守护程序 APIs，后者充当 SDK 发出的 API 调用的 TCP 代理，则可能会发生这种情况。

您还可以将 SDK 配置为从 JSON 文档加载采样规则。在 X-Ray 采样不可用的情况下，SDK 可以使用本地规则作为备份，也可以只使用本地规则。

**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
  }
}
```

此示例定义了一个自定义规则和一个默认规则。自定义规则采用百分之五的采样率，对于 `/api/move/` 之下的路径要跟踪的请求数量不设下限。默认规则中每秒的第一个请求以及其他请求的百分之十。

在本地定义规则的缺点是，固定目标由记录器的每个实例独立应用而不是由 X-Ray 服务管理。随着您部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。

开启后 Amazon 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)
```

## 日志记录


开发工具包使用 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)时，使用调试日志来识别诸如未结束子分段之类的问题。

## 代码中的记录器配置


其他设置包含在 `xray_recorder` 的 `configure` 方法中。
+ `context_missing` - 设置为 `LOG_ERROR` 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。
+ `daemon_address` - 设置 X-Ray 进程守护程序侦听器的主机和端口。
+ `service` - 设置开发工具包用于进行分段的服务名称。
+ `plugins`— 记录有关您的应用程序 Amazon 资源的信息。
+ `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 时的记录器配置


如果您使用 Django 框架，您可以使用 Django `settings.py` 文件来配置全局记录器的选项。
+ `AUTO_INSTRUMENT`（仅限 Django） - 记录内置数据库和模板渲染操作的子分段。
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `LOG_ERROR` 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。
+ `AWS_XRAY_TRACING_NAME` - 设置开发工具包用于进行分段的服务名称。
+ `PLUGINS`— 记录有关您的应用程序 Amazon 资源的信息。
+ `SAMPLING` 设置为 `False` 可禁用采样。
+ `SAMPLING_RULES` - 设置包含您的[采样规则](#xray-sdk-python-configuration-sampling)的 JSON 文件的路径。

要启用 `settings.py` 中的记录器配置，请将 Django 中间件添加到已安装应用程序列表中。

**Example settings.py - 已安装的应用程序**  

```
INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]
```

在名为 `XRAY_RECORDER` 的 dict 中配置可用设置。

**Example 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,
}
```

## 环境变量


您可以使用环境变量配置适用于 Python 的 X-Ray 开发工具包。开发工具包支持以下变量：
+ `AWS_XRAY_TRACING_NAME` - 设置 SDK 用于进行分段的服务名称。覆盖您以编程方式设置的服务名称。
+ `AWS_XRAY_SDK_ENABLED` - 如果设置为 `false`，则会禁用开发工具包。默认情况下，开发工具包处于启用状态，除非环境变量设置为 false。
  + 禁用时，全局记录器会自动生成不发送到进程守护程序的虚拟分段和子分段，并禁用自动修补。中间件是作为全局记录器的包装器编写的。通过中间件生成的所有分段和子分段也成为虚拟分段和虚拟子分段。
  + 通过环境变量设置 `AWS_XRAY_SDK_ENABLED` 值，或者通过与 `aws_xray_sdk` 库中 `global_sdk_config` 对象的直接交互来设置。环境变量的设置会覆盖这些交互。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。默认情况下，SDK 使用用于跟踪数据（UDP）和采样（TCP）的 `127.0.0.1:2000`。如果您已将进程守护程序配置为[侦听不同端口](xray-daemon-configuration.md)或者进程守护程序在另一台主机上运行，则使用此变量。

**Format**
  + **同一个端口** — `address:port`
  + **不同的端口** — `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `RUNTIME_ERROR` 在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

**有效值**
  + `RUNTIME_ERROR`— 引发运行时异常。
  + `LOG_ERROR`— 记录错误并继续（默认）。
  + `IGNORE_ERROR`— 忽略错误并继续。

  对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。

环境变量覆盖在代码中设置的值。

# 使用适用于 Python 中间件的 X-Ray 开发工具包跟踪传入请求
传入请求

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

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

适用于 Python 的 X-Ray 开发工具包支持以下中间件来检测传入的 HTTP 请求：
+ Django
+ Flask
+ Bottle

**注意**  
对于 Amazon Lambda 函数，Lambda 会为每个采样请求创建一个分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。

有关在 Lambda 中检测过的示例 Python 函数，请参阅[工作线程](scorekeep-lambda.md#scorekeep-lambda-worker)。

对于其他框架上的脚本或 Python 应用程序，您可以[手动创建分段](#xray-sdk-python-middleware-manual)。

每个分段都有一个名称，用于在服务映射中标识您的应用程序。可以静态命名分段，也可以将 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`。

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


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

**Example settings.py - 适用于 Python 中间件的 X-Ray 开发工具包**  

```
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 开发工具包 Django 添加到 `settings.py` 文件中的 `INSTALLED_APPS` 列表。这将允许在应用程序启动期间配置 X-Ray 记录器。

**Example settings.py - 适用于 Python Django 应用的 X-Ray 开发工具包**  

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


要检测您的 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)


要检测您的 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 代码


如果您不使用 Django 或 Flask，则可以手动创建分段。您可以为每个传入的请求创建区段，也可以围绕已修补的 HTTP 或 Amazon SDK 客户端创建区段，为录制器添加子分段提供上下文。

**Example 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()
```

## 配置分段命名策略


Amazon X-Ray 使用*服务名称*来标识您的应用程序，并将其与您的应用程序使用的其他应用程序、数据库 APIs、外部数据库和 Amazon 资源区分开来。当 X-Ray SDK 为传入请求生成分段时，会将应用程序的服务名称记录在分段的[名称字段](xray-api-segmentdocuments.md#api-segmentdocuments-fields)中。

X-Ray SDK 可以用在 HTTP 请求标头中的 hostname 来命名分段。不过，此标头可以伪造，会导致服务地图中出现意料之外的节点。为防止 SDK 由于包含伪造的主机标头的请求而错误地命名分段，必须为传入请求指定一个默认名称。

如果应用程序为多个域的请求提供服务，则可以将 SDK 配置为使用动态命名策略以在分段名称中反映出这一点。动态命名策略允许 SDK 将主机名用于符合预期模式的请求，并将默认名称应用于不符合预期模式的请求。

例如，可能有一款应用程序为发送到三个子域的请求提供服务，分别为 `www.example.com`、`api.example.com` 和 `static.example.com`。可以使用格式 `*.example.com` 的动态命名策略以识别包含不同名称的子域的分段，服务地图上因此会显示三个服务节点。如果应用程序收到包含与该格式不匹配的 hostname 的请求，您将会在服务地图上看到第四个节点，以及您指定的回退名称。

要对所有请求分段使用相同名称，请在配置记录器时指定应用程序的名称，如[前几节](#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)覆盖您在代码中定义的默认服务名称。

# 修补库以检测下游调用
修补库

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

要检测下游调用，请使用适用于 Pyhon 的 X-Ray 开发工具包修补您的应用程序使用的库。适用于 Python 的 X-Ray 开发工具包可以修补以下库。

**支持的库**
+ `[botocore](https://pypi.python.org/pypi/botocore)`，`[boto3](https://pypi.python.org/pypi/boto3)`— 仪器 Amazon SDK for Python (Boto) 客户。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` - 检测 Amazon DynamoDB 客户端的 PynamoDB 版本。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、`[aioboto3](https://pypi.python.org/pypi/aioboto3)` - 检测 SDK for Python 客户端的 [asyncio](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/)` - 检测 Pure-Python PostgreSQL 接口。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` - 检测 PostgreSQL 数据库适配器。
+ `[pymongo](https://pypi.org/project/pymongo/)` - 检测 MongoDB 客户端。
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— 针对 My PyMy SQL 和 MariaDB 的基于 SQL 的客户端。

如果您使用已修补的库，适用于 Pyhon 的 X-Ray 开发工具包会为调用创建子分段，并记录请求和响应中的信息。必须通过开发工具包中间件或 Amazon Lambda提供分段，以供开发工具包创建子分段。

**注意**  
如果您使用 SQLAlchemy ORM，则可以通过导入 SDK 版本的会话和查询类 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)`

## 跟踪异步工作的上下文


对于集成了 `asyncio` 的库，或者要[为异步函数创建子分段](xray-sdk-python-subsegments.md)，您还必须使用异步上下文配置适用于 Pyhon 的 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)
```

# 使用 Amazon 适用于 Python 的 X-Ray 软件开发工具包追踪 SDK
Amazon SDK 客户端

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

当您的应用程序调用 Amazon Web Services 服务 以存储数据、写入队列或发送通知时，适用于 Python 的 X-Ray SDK 会在[子分段](xray-sdk-python-subsegments.md)中跟踪下游的调用。在这些服务（例如，Amazon S3 存储桶或 Amazon SQS 队列）中追踪的资源 Amazon Web Services 服务 和访问的资源在 X-Ray 控制台的跟踪地图上显示为下游节点。

当你[修补`botocore`库](xray-sdk-python-patching.md)时，适用于 Python 的 X-Ray Amazon SDK 会自动检测所有 SDK 客户端。您无法检测单个客户端。

对于所有服务，都可以在 X-Ray 控制台中看到调用的 API 的名称。X-Ray 开发工具包会为一部分服务将信息添加到分段，从而在服务地图中提供更高的粒度。

例如，当使用经过检测的 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 服务的调用
传出 HTTP 调用

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

当您的应用程序调用微服务或公共 HTTP 时 APIs，您可以使用适用于 Python 的 X-Ray SDK 来检测这些调用，并将该 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` 的客户端 API。

**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 开发工具包生成自定义子分段
自定义子分段

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

子分段可为跟踪的[分段](xray-concepts.md#xray-concepts-segments)扩展为了给请求提供服务而已完成的工作的详细信息。每次使用已检测的客户端进行调用时，X-Ray SDK 在子分段中记录生成的信息。您可以创建其他子分段来分组其他子分段，来度量某个代码段的性能如何，或是来记录注释和元数据。

要管理子分段，请使用 `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"
    }
  },
```

# 使用 X-Ray SDK for Python，将注释和元数据添加到分段
注释和元数据

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

可以利用注释和元数据记录与请求、环境或应用程序相关的其他信息。可以将注释和元数据添加到 X-Ray 开发工具包创建的分段或您创建的自定义子分段。

**注释**是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与[筛选表达式](xray-console-filters.md)一起使用。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 [https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html](https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html) API 时使用的数据。

**元数据**是可以具有任何类型值的键-值对，包括对象和列表，但没有编制索引，无法与筛选条件表达式一起使用。使用元数据记录要存储在跟踪中但不需要用于搜索跟踪的其他数据。

除了注释和元数据之外，您还可以在分段上[记录用户 ID 字符串](#xray-sdk-python-segment-userid)。用户 IDs 被记录在区段的单独字段中，并编制索引以供搜索使用。

**Topics**
+ [

## 使用 X-Ray SDK for Python 记录注释
](#xray-sdk-python-segment-annotations)
+ [

## 使用 X-Ray SDK for Python 记录元数据
](#xray-sdk-python-segment-metadata)
+ [

## 使用适用于 Python 的 X-Ray SDK 录制用户 IDs
](#xray-sdk-python-segment-userid)

## 使用 X-Ray SDK for Python 记录注释


使用注释记录有关要为其编制索引以进行搜索的分段和子分段的信息。

**注释要求**
+ **键** - 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");
   ```

此外，您还可以使用对 `put_annotation` 使用 `xray_recorder` 方法。此方法会记录当前子分段上的注释，如果未打开子分段，则记录分段上的注释。

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

开发工具包将注释以键-值对的形式记录在分段文档的 `annotations` 对象中。使用相同键调用两次 `put_annotation` 将覆盖同一分段或子分段上之前记录的值。

要查找具有带特定值的注释的跟踪，请在`annotation[key]`筛选表达式[中使用 ](xray-console-filters.md) 关键字。

## 使用 X-Ray SDK for Python 记录元数据


**警告**  
请勿在 X-Ray SDK for Python 中将存在循环引用的对象作为元数据值添加。这些对象无法序列化为 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");
   ```

此外，您还可以使用对 `put_metadata` 使用 `xray_recorder` 方法。此方法会记录当前子分段上的元数据，如果未打开子分段，则记录分段上的元数据。

```
xray_recorder.put_metadata("my key", "my value");
```

如果您没有指定命名空间，则开发工具包将使用 `default`。使用相同键调用两次 `put_metadata` 将覆盖同一分段或子分段上之前记录的值。

## 使用适用于 Python 的 X-Ray SDK 录制用户 IDs


记录请求细分中的用户，以识别发送请求的用户。 IDs 

**要记录用户 IDs**

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 的跟踪，请在`user`筛选表达式[中使用 ](xray-console-filters.md) 关键字。

# 检测部署到无服务器环境的 Web 框架
检测无服务器应用程序

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

适用于 Python 的 Amazon X-Ray SDK 支持对部署在无服务器应用程序中的网络框架进行检测。无服务器是云端原生架构，可让您将更多的运营职责切换到 Amazon，帮助您提升灵活性和创新。

无服务器架构是一种软件应用程序模式，让您无需考虑服务器的问题即可构建和运行应用程序和服务。为您省去基础设施管理任务，例如，服务器或集群预配、修补、操作系统维护，以及容量预配。几乎可以为任何类型的应用程序或后端服务构建无服务器解决方案，即可为您处理好运行和缩放高可用性应用程序所需要的一切。

本教程向您展示了如何在部署到无服务器 Amazon X-Ray 环境的 Web 框架（例如 Flask 或 Django）上自动进行检测。应用程序的 X-Ray 检测允许您查看所有下游调用，从 Amazon API Gateway 到您的 Amazon Lambda 函数，以及您的应用程序发出的传出调用。

适用于 Python 的 X-Ray 开发工具包支持以下 Python 应用程序框架：
+ FLASK 版本 0.8 或更高版本
+ Django 版本 1.0 或更高版本

本教程开发了一款示例无服务器应用程序部署到 Lambda，由 API Gateway 调用。本教程使用 Zappa 自动将应用程序部署到 Lambda 并配置 API Gateway 端点。

## 先决条件

+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-python.html) - 版本 2.7 或 3.6。
+ [Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-configure.html)— 验证您的账户 Amazon CLI 是否配置 Amazon Web Services 区域 了以及您将在其中部署应用程序。
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)

## 步骤 1：创建 环境


在此步骤中，您将创建一个使用 `virtualenv` 托管应用程序的虚拟环境。

1. 使用 Amazon 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` 目录中。在这个例子中，我们可以构建 Flash 的 [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) 示例。

   在 `serverless_application` 目录中创建名为 `my_app.py` 的文件。然后使用文本编辑器添加以下命令。此应用程序将检测 Requests 库，修补 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 环境


在此步骤中，您将使用 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 跟踪


在此步骤中，您将与 API Gateway 控制台进行交互以启用 X-Ray 跟踪。

1. 登录 Amazon Web Services 管理控制台 并打开 API Gateway 控制台，网址为[https://console.aws.amazon.com/apigateway/](https://console.amazonaws.cn/apigateway/)。

1. 找到新生成的 API。它应该类似于 `serverless-exam-dev`。

1. 选择**阶段**。

1. 选择部署阶段的名称。默认值为 `dev`。

1. 在**日志/跟踪**选项卡上，选中**启用 X-Ray 跟踪**复选框。

1. 选择**保存更改**。

1. 在浏览器中访问端点。如果您使用了示例 `Hello World` 应用程序，它应显示以下内容。

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

## 步骤 4：查看创建的跟踪


在此步骤中，您将与 X-Ray 控制台交互，以查看示例应用程序所创建的跟踪。有关跟踪分析的更详细演练，请参阅[查看服务映射](https://docs.amazonaws.cn/xray/latest/devguide/xray-console.html#xray-console-servicemap)。

1. 登录 Amazon Web Services 管理控制台 并在[https://console.aws.amazon.com/xray/家](https://console.amazonaws.cn/xray/home)中打开 X-Ray 控制台。

1. 查看 API Gateway、Lambda 函数和 Lambda 容器生成的分段。

1. 在 Lambda 函数分段下，查看名为 `My First Serverless App` 的子分段。紧随其后的是名为 `https://aws.amazon.com` 的第二个子段。

1. 在初始化期间，Lambda 可能还会生成名为 `initialization` 的第三个子分段。

![\[跟踪分段视图。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/serverless-traceView.png)


![\[服务图视图。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/serverless-serviceView.png)


## 第 5 步：清理


始终终止不再使用的资源，以避免意外的成本累积。正如本教程所演示的那样，Zappa 此类工具可以简化无服务器部署。

要从 Lambda、API Gateway 和 Amazon S3中删除应用程序，请通过使用 Amazon CLI从项目目录中运行以下命令。

```
zappa undeploy dev
```

## 后续步骤


通过添加 Amazon 客户端并使用 X-Ray 对其进行检测，为您的应用程序添加更多功能。若要详细了解无服务器计算选项，请前往 [Amazon上的无服务器](https://www.amazonaws.cn/serverless)。