Python Agent 集成

本文档详细介绍了 python agent 与您应用程序的集成信息。

目录

总览

Python Agent 需要和应用程序集成后才可以开始监控,您可以通过以下两种方式进行设置:

  • 使用 wrapper script 激活 WSGI 服务器或者 web 应用。该脚本可以在 python 解析器启动时自动初始化 agent。wrapper script 不需要您更改被监控的应用,但是只能在受您控制的 WSGI 服务器或者 web 应用中使用。

  • 手动修改 WSGIscript 文件– 该文件用于 WSGI 服务器或者主 web 应用启动脚本,以添加 API 调用来初始化 agent。

注意:wrapper script 在内嵌 python 环境(例如 Apache/mod_wsgi)中不可用。若一个 python 环境在使用用户生成的 sitecustomize.py 文件,wrapper script 可能也不可用。这种情况会在使用 buildout 安装某些包装环境时发生。

如果您在使用支持的 web 框架,这些都是必须的。如果您使用的是不支持的Web框架,或正在搭建一个使用 WSGI 组件库(如 Werkzeug 或 Paste)的 WSGI 应用,您可能还需要手动包装 WSGI 应用程序的入口点。

Agent安装以及测试

在阅读下面 Agent 和您应用程序的集成说明之前,请确保已经安装 Agent 应用程序,并且测试了安装的可用性。如果您还没有这样做,请查看:

  1. Python 安装方法
  2. 测试 Python agent

运行 wrapper script

注意:以下说明基于您使用 Bourne Style shell 的假设上。具体根据您自己的 shell,您可能需要做部分调整。

在运行一个独立的 WSGI 服务器或 Web 应用时使用 wrapper script,您需要:

  1. 更改现有的启动命令。
  2. 设置环境变量,识别 wrapper script 中 agent 配置文件的位置信息或者 license key 的值。

blueware-admin 作为您之前在启动 WSGI 服务器或 Web 应用时的现存的完整命令的前缀,并且需要与 run-program 选项共同运行。

旧命令形式 新命令形式
command options BLUEWARE_CONFIG_FILE=blueware.ini blueware-admin run-program command options
VARIABLE=value command options BLUEWARE_CONFIG_FILE=blueware.ini VARIABLE=value blueware-admin run-program command options

跨行命令拆分

可以在运行 wrapper script 之前,您需要导出 BLUEWARE_CONFIG_FILE 环境变量。

export BLUEWARE_CONFIG_FILE=blueware.ini 
blueware-admin run-program command options 

如果使用 exec 启动命令,您需要从 wrapperscript 的执行中分离出环境变量的设置。

export BLUEWARE_CONFIG_FILE=blueware.ini 
exec blueware-admin run-program command options

如果您使用的是进程管理系统(如 supervisord),那么环境变量需要在单独的配置文件中设置,并且您不能将它们设置在同一行的命令中。

例如,在 supervisord 系统中,您可以使用:

[program:warpdrive] 
command = blueware-admin run-program command options 
environment = BLUEWARE_CONFIG_FILE=blueware.ini

运行python可执行文件

如果命令行运行的是 python 可执行文件,且直接运行 python 代码文件,如 "python main.py",可使用以下任意一个命令:

blueware-admin run-program python main.py  
blueware-admin run-python main.py

使用 run-python 会使用和已安装 blueware-admin 的 python 环境或虚拟环境中的 python 可执行文件。

blueware-admin 的位置

您运行的 blueware-admin 程序和您的应用程序必须在同一个 python 环境(包括虚拟环境)下。您不能将不同的 python 环境混在一起,否则 Agent 将不能正常运行。

wrapper script 可能运行方式:

说明 示例代码
在 WSGI 应用中直接运行 gunicorn BLUEWARE_CONFIG_FILE=blueware.ini blueware-admin run-program gunicorn -w 3 wsgi:application
通过 run_gunicorn 命令运行 Django BLUEWARE_CONFIG_FILE=blueware.ini blueware-admin run-python manage.py run_gunicorn -w 3
在 WSGI 应用中直接运行 uWSGI BLUEWARE_CONFIG_FILE=blueware.ini blueware-admin run-program uwsgi --socket /tmp/uwsgi.sock --single-interpreter --enable-threads wsgi.py
在 WSGI 应用指定的 pasterini 配置文件中运行 paster server BLUEWARE_CONFIG_FILE=blueware.ini blueware-admin run-program paster serve production.ini

手动代码集成

如果您不能使用 wrapper script,您需要手动集成初始化 python agent 的请求到 web 应用中。这在您使用内嵌 python 环境时是必要的。您也可以决定是否使用 wrapper script。

对于手动集成,您需要在 WSGI 应用脚本文件或者控制WSGI应用起始点的模块的开始部分添加下列代码:

import blueware.agent
blueware.agent.initialize('/some/path/blueware.ini')

将 "/some/path/blueware.ini" 替换为安装中生成的配置文件的位置。该配置文件对您的 web 应用来说必须是可读的。

在和特定部署环境对应的 agent 配置文件内部确定覆盖时,环境名称应作为 "initialize()" 函数的第二个参数。

import blueware.agent
blueware.agent.initialize('/some/path/blueware.ini', 'staging')

如果您已经在 Python 的虚拟环境中安装了 OneAPM 的 Python 包,上述代码必须在您激活或已设置 'sys.path' 来查找虚拟环境之后添加。

上述应尽量在任何将被监控的模块导入之前完成。对于一些 web 框架,包括 flask,这是强制性的操作。如果没有在导入之前放置,监控程序将无法正常工作。

如果您没有使用 wrapper script 但仍希望使用环境变量 BLUEWARE_CONFIG_FILE 和 BLUEWARE_ENVIRONMENT 来配置 agent,您可以调用不含任何参数的 "initialize()" 函数,它们会被自动导入。

import blueware.agent
blueware.agent.initialize()

或者,如果默认的其他所有配置都正确的话,您可以设置 BLUEWARE_LICENSE_KEY 和 BLUEWARE_APP_NAME 环境变量。

注意:即使使用嵌入式环境,如 Apache/mod_wsgi 时,您不能依赖于从环境变量中获得配置。这是因为在嵌入式系统中,往往是您不能设置进程的环境变量,但是反过来,这些变量对 WSGI 脚本文件又是可用的。

包装WSGI应用

当支持的 Web 框架正在被使用时,使用 wrapper script 或添加的 API 调用来显式初始化 Agent。WSGI 应用程序入口点的 Web 框架将自动监控,以便监视每一个 Web 请求。

如果您使用的是不支持的 Web 框架,或利用 WSGI 组件库(如 Werkzeug 或 Paste)搭建的 WSGI 应用,您可能还需要手动包装 WSGI 应用程序的入口点。

如果 WSGI 应用程序的入口点是其文件中声明的一个函数,使用以下修饰:

@blueware.agent.wsgi_application()
def application(environ, start_response): ...

如果 WSGI 应用的入口点是从不同的模块导入的函数或对象,需要用一个包装对象来包装它:

import myapp
application = myapp.WSGIHandler()  
application = blueware.agent.WSGIApplicationWrapper(application)

如果正在使用支持的 Web 框架,您可能仍然使用显式的修饰器或包装器,比如,您在支持的 Web 框架周围添加额外的 WSGI 中间件的时候。这将确保所有的 WSGI 中间件的运行都能被 agent 监控到。

日志模块配置

Python Agent 将通过 Python 的日志模块,记录有关正在执行的操作信息,以及其他调试信息。如果 agent 正与一个配置了 Python 日志记录模块的应用结合使用,为确保该 Agent 日志记录能够被正确捕获,您可能需要对记录模块的配置做出相应更改。

有关详情请参阅 Python 的 Agent 日志记录。

还有其他问题? 提交请求

您还可以采取以下方式解决问题: