适用于 Python 的 AWS X-Ray 开发工具包 - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

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

可以使用 pip 下载开发工具包。

$ pip install aws-xray-sdk
注意

X-Ray SDK for Python 是一个开源项目。您可以跟踪该项目并在 GitHub 上提交问题和拉取请求:github.com/aws/aws-xray-sdk-python

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

对于由已分析应用程序或服务调用的 Lambda 函数,Lambda 自动读取跟踪标头并跟踪采样的请求。对于其他函数,您可以配置 Lambda 以采样和跟踪传入请求。无论哪种情况,Lambda 都会创建分段并将其提供给 X-Ray 开发工具包。

注意

在 Lambda 上,X-Ray 开发工具包是可选的。如果您不将它用于您的函数,则您的服务地图仍将为 Lambda 服务包含节点,每个 Lambda 函数各一个。通过添加开发工具包,您可以分析您的函数代码,以将子分段添加到 Lambda 所记录的函数分段。请参阅 AWS Lambda 和 AWS X-Ray 以了解更多信息。

有关在 Lambda 中分析过的示例 Python 函数,请参阅工作线程

接下来,通过修补应用程序的库,使用X-Ray SDK for Python分析下游调用。开发工具包支持以下库。

支持的库

  • botocoreboto3 – 分析 AWS SDK for Python (Boto) 客户端。

  • pynamodb – 分析 Amazon DynamoDB 客户端的 PynamoDB 版本。

  • aiobotocoreaioboto3 – 分析集成了 asyncio 的 SDK for Python 客户端版本。

  • requests, aiohttp – 分析高级别 HTTP 客户端。

  • httplibhttp.client – 分析低级别 HTTP 客户端和使用这些客户端的更高级别的库。

  • sqlite3 – 分析 SQLite 客户端。

  • mysql-connector-python – 分析 MySQL 客户端。

  • pg8000 – 分析 Pure-Python PostgreSQL 接口。

  • psycopg2 – 分析 PostgreSQL 数据库适配器。

  • pymongo – 分析 MongoDB 客户端。

  • pymysql – 分析基于 PyMySQL 的客户端以用于 MySQL 和 MariaDB。

每当您的应用程序调用 AWS、SQL 数据库和其他 HTTP 服务时,开发工具包都会记录有关子分段中的调用的信息。AWS 服务以及您在该服务中访问的资源将在服务地图上显示为下游节点,以帮助您在各个连接上识别错误和限制问题。

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

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

注释和元数据

注释和元数据是您用 X-Ray 开发工具包添加到分段中的任意文本。会对注释编制索引,用于与筛选表达式一同使用。不会对元数据编制索引,但是可以在原始分段中通过 X-Ray 控制台或 API 查看。您授予对 X-Ray 读取权限的人都可以查看此数据。

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

有关开发工具包的类和方法的参考文档,请参阅适用于 Python API 的 AWS X-Ray 开发工具包参考

要求

X-Ray SDK for 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 和更新版本

依赖项管理

X-Ray SDK for Python可从 pip 获得。

  • 程序包aws-xray-sdk

在您的 requirements.txt 文件中添加开发工具包作为依赖项。

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