View a markdown version of this page

AWS X-Ray 适用于 Python 的开发工具包 - AWS X-Ray
要求依赖关系管理

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

AWS X-Ray 适用于 Python 的开发工具包

注意

X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在此模式下， X-Ray SDK 和守护程序的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 X-Ray SDK 和 Daemon Support 时间表。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅从 X-Ray 仪器仪器迁移到仪器 OpenTelemetry 仪表。

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

可以使用 pip 下载 SDK。

$ pip install aws-xray-sdk
注意

Python X-Ray 开发工具包是一个开源项目。你可以关注该项目并在 github 上 GitHub提交议题和拉取请求。com/aws/aws-xray-sdk-python

如果您使用的是 Django 或 Flask，请首先将 SDK 中间件添加到您的应用程序以跟踪传入请求。此中间件为每个被跟踪请求创建一个分段并在发送响应时完成该分段。当分段打开时，您可以使用开发工具包客户端的方法将信息添加到分段，并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。对于其他应用程序，您可以手动创建分段。

对于由经过检测的应用程序或服务调用的 Lambda 函数，Lambda 会读取跟踪标头并自动跟踪采样的请求。对于其他函数，您可以将 Lambda 配置为采样和跟踪传入请求。无论哪种情况，Lambda 都会创建该分段并将其提供给 X-Ray SDK。

注意

在 Lambda 上， X-Ray 软件开发工具包是可选的。如果您不在函数中使用它，您的服务映射仍将包含一个用于 Lambda 服务的节点，以及每个 Lambda 函数的节点。可通过添加该开发工具包检测函数代码，将子分段添加到 Lambda 记录的函数分段。请参阅AWS Lambda 和 AWS X-Ray了解更多信息。

有关在 Lambda 中检测过的示例 Python 函数，请参阅工作线程。

接下来，使用 X-Ray 适用于 Python 的开发工具包通过修补应用程序的库来检测下游调用。该 SDK 支持以下库。

支持的库

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

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

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

注释和元数据

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

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

有关 SDK 的类和方法的参考文档，请参阅 AWS X-Ray SDK for Python API 参考。

要求

X-Ray 适用于 Python 的软件开发工具包支持以下语言和库版本。

  • Python - 2.7、3.4 和更新版本

  • Django - 1.10 和更新版本

  • Flask - 0.10 和更新版本

  • aiohttp - 2.3.0 和更新版本

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

依赖关系管理

适用于 Python 的 X-Ray SDK 可从中获得pip。

  • 程序包 - aws-xray-sdk

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

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