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

# Amazon X-Ray Python 软件开发工具包
<a name="xray-sdk-python"></a>

**注意**  
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)。

## 要求
<a name="xray-sdk-python-requirements"></a>

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 和更新版本

## 依赖关系管理
<a name="xray-sdk-python-dependencies"></a>

可从 `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` 中的所有程序包。