简述听云 python 探针 ( 也称 Python Agent) 是基于 Python 语言而研发的性能监测工具客户端, 其主要目标为支持 WSGI 协议的 python web 框架理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测, 比如 django tornado fla

Size: px

Start display at page:

Download "简述听云 python 探针 ( 也称 Python Agent) 是基于 Python 语言而研发的性能监测工具客户端, 其主要目标为支持 WSGI 协议的 python web 框架理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测, 比如 django tornado fla"

条欣瞿
5 years ago
Views:

1 Python 探针用户指南北京基调网络股份有限公司 1 / 16

2 简述听云 python 探针 ( 也称 Python Agent) 是基于 Python 语言而研发的性能监测工具客户端, 其主要目标为支持 WSGI 协议的 python web 框架理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测, 比如 django tornado flask 等当然其中也包括一些该 web 框架支持的一些外围组件, 例如 sql 数据库 nosql 数据库第三方 http 调用等其功能会随着版本的升级而得到更多的支持本文档所列明的支持的框架数据库软件环境等, 是经过测试, 且完全支持的对于没有在本文档列出的框架以组件安装方式等将不被支持, 但随着版本的更新会逐步完善在使用听云 python 探针前请务必仔细阅读此文档, 同时我们也极力保持文档与探针功能的同步更新探针在性能监测时, 将会对页面加载模板渲染中间件调用视图层数据层系统软件环境硬件环境等数据进行跟踪和监测, 更多关于监测的数据参考平台的数据监测欢迎使用听云, 因为有你, 我们将会做的更好!! 听云 python 团队 2 / 16

3 一快速入门 1 环境要求环境要求备注操作系统类 unix 系统, 如 linux FreebSD MacOS X 等 windows 未经测试 Python Cpython 2.6.x,2.7.x web 框架 django 建议 v1.3-v1.6 稳定版本使用范围兼容 WSGI 1.0 (PEP 333) 2 快速安装解压安装包, 并进入安装目录, 例如 : tar -zxvf tingyun-agent-python tar.gz -C /tmp/ cd /tmp/tingyun-agent-python / 执行 python setup.py install 找到 tingyun-agent-python 中的配置文件 tingyun.ini, 并设置您的 license_key, 如果需要可配置 log 以及相关信息 vi /tmp/tingyun-agent-python /tingyun.ini 修改您的 license_key 设置探针配置文件环境变量, 例如 : export TING_YUN_CONFIG_FILE=/tmp/ tingyun-agent-python /tingyun.ini (ini 配置文件随安装包发布 ) 命令行执行 tingyun-admin run-program 您应用的启动命令应用参数例如,tingyun-admin run-program./uwsgi.sh start 3 / 16

4 二安装与配置目前探针支持以下安装方式, 建议使用虚拟环境, 如 virtualenv, 统环境 : pyvenv 避免污染系安装方式执行命令备注源码安装 python setup.py install 从获取源码 1 探针的安装 1.1 探针源码安装假设得到的安装包为 tingyun-agent-python tar.gz 执行 tar zxvf tingyun-agent-python tar.gz 解压到当前目录, 解压后将会得到如下目录 tingyun-agent-python 进入解压后的目录执行 python setup.py install, 即可将探针安装到当前的 python 环境 4 / 16

5 2 探针升级 2.1 源码升级源码方式升级探针, 只需重新执行安装即可覆盖旧版本详情参考 < 探针源码安装 > 5 / 16

6 3 探针卸载 3.1 源码安装方式的卸载如果以源码方式安装的探针, 卸载探针时, 只需将探针安装目录下的 tingyun 包 ( 通常在 site-packages 下 ) 以及可执行目录下的 tingyun-admin 删除即可 6 / 16

7 4 探针的配置本小节主要讨论探针的本地配置, 在安装包中提供了一份默认的配置文件 tingyun.ini, 该配置为标准 python ini 文件配置, 详情参考在使用时需要为该配置文件配置环境变量 TING_YUN_CONFIG_FILE, 探针方能启动配置文件 tingyun.ini 中除了 license key log_file 之外均有默认值 ( 即使没有配置 ), 为了正常使用探针,license key 是必填项, 详情请参考下述说明 Section 配置项备注 tingyun license_key 字符型 enabled Boolean 型 app_name 字符型 log_file 字符型 audit_mode Boolean 型 log_level 字符型 ssl Boolean 型 auto_action_naming Boolean 型 action_tracer.log_sql Boolean 型注 : 本地配置的修改需重启方能生效! 4.1 license_key 功能 : 账户认证标识, 必填项, 使用探针前请务必填写该项默认值 : 无说明 : 如缺少该配置项或者配置项错误, 探针能正常启动,log 输出会提示 license 无效, 将不会采集并上报数据 4.2 enabled 功能 : 客户端开启禁用探针开关默认值 :True, 可选值 True, False, 以及 on, off, 不区分大小写说明 : 如缺少该配置项或者配置项错误, 探针将使用值 True, 开启探针功能 4.3 app_name: 功能 : 监控的应用名字默认值 :Python App 7 / 16

8 数据说明 : 如缺少该配置项空值错误值等, 将使用值 Python App 作为应用的名字上报 4.4 log_file 功能 : 指定探针 log 写入的文件名以及路径, 推荐使用绝对路径默认值 : 无, 支持自定义系统文件路径 stdout stderr 说明 : 若缺少该配置空值错误值等, 探针可正常启动,log 将会输出到 stderr 若指定了 stdout 或者 stderr, 将会定向到系统标准输出由于 python 的 log 分割机制有缺陷, 探针将会向一份日志文件中输出日志, 请做好日志处理请确保您应用进程的用户对该目录和 log 文件有写入权限, 否则将会输出到 stderr 4.5 log_level 功能 : 指定探针 log 的日志级别默认值 :INFO, 可选值 DEBUG,INFO, WARNING,ERROR,CRITICAL ( 不区分大小写 ) 说明 : 若缺少该配置, 或错误配置将默认使用 INFO 级别 4.6 ssl 功能 : 指定使用 http 或 https 传输协议默认值 :True, 可选值 True, False, 以及 on, off, 不区分大小写说明 : 若缺少该配置配置错误等, 将使用值 True, 使用 https 协议传输数据 4.7 audit_mode 功能 : 是否将提交上报的数据将会输出到 log 中以备审计,False 关闭审计, 反之开启 ( 该 log 以 INFO 级别输出 ) 默认值 :False, 可选值 True, False, 以及 on, off, 不区分大小写说明 : 若缺少该配置配置错误等, 将使用值 False, 关闭审计模式该部分 log 将以 Agent capture the web component 开头 4.8 auto_action_naming 功能 : 设置是否开启自动命名, 如开启自动命名,uri 名字将会做为 action 的名字默认值 : True, 可选值 True, False, 以及 on, off, 不区分大小写说明 : 若缺少该配置配置错误等, 将使用值 True, 开启自动命名 8 / 16

9 4.9 action_tracer.log_sql 功能 : 事务跟踪时 SQL 语句的记录只写到本地日志文件中, 不提交到数据采集服务上 ( 输出级别为 INFO 级别 log) 默认值 : False, 可选值 True, False, 以及 on, off, 不区分大小写说明 : 若缺少该配置配置错误等, 将使用值 False, 该部分 log 将以 Log sql is opened 开头 9 / 16

10 三使用与维护 1 局限性限制由类似 greenlet 等第三方协程线程调用模块其监测性能数据可能会有偏差, 或错误未在本文档内注明支持的其他框架模块随着探针升级更多的框架组件将得到支持, 敬请期待 2 探针使用为了响应更多的需求, 我们将会根据客户的反应需求以及探针自身的因素, 进行不定期的升级为了更好的用户使用体验, 升级后我们会第一时间通知您, 届时请升级到最新版同时也欢迎您向我们提供宝贵的意见与建议! 探针启动目前探针的启动方式为伴随着 python 解释器启动而启动, 也就是说您只需要在您的应用程序启动命令前加上探针命令以及参数, 探针就已经启动了, 支持以下方式启动探针 : 探针命令行命令探针命令行参数您的应用程序以及参数 tingyun-admin run-program 例如 : tingyun-admin run-program python runserver tingyun-admin run-program uwsgi_shell.sh start 注意 : 探针仅支持满足 WSGI 协议的 web 应用, 其他类型的应用的数据将不会被监测探针停止探针会随着您应用程序的停止而停止, 所以大致有以下两种正常的停止方式 : 直接使用您应用程序的停止方式停止探针, 如 uwsgi_shell.sh stop 使用探针命令方式停止探针, 如 tingyun-admin run-program uwsgi_shell.sh stop 10 / 16

11 3 探针的维护如果配置了 log( 建议配置 log), 探针的所有信息将会更具日志级别输出到 log 中, 如果发现有任何异常, 可根据 log 输出, 获取更多的支持和帮助若需获取更多的帮助, 请联系我们的技术支持 11 / 16

12 四支持框架听云 python 探针是根据 WSGI 协议而为 web 框架定制的性能监测客户端, 理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测当然其中也包括一些该 web 框架支持的一些 python 的第三方包, 例如 sql 数据库 nosql 数据库第三方 http 调用等其功能会随着版本的升级而得到更多的支持, 目前其支持的组件以及框架结构如下所述目前所有的组件, 包括数据库第三方调用等, 均没有提供独立的 api, 都依赖于 web 框架而存在 1 框架 1.1 django 的支持 django 符合 WSGI 标准, 理论上所有的版本都能支持, 这里建议使用 1.3.x 以上版本其支持情况如下所示组件 uwsgi 必须开启以下选项 : --enable-threads --single-interpreter gunicorn mod_wsgi 说明支持请求中间件. 支持视图中间件. 支持模板响应中间件. 支持响应中间件. 支持异常中间件. 支持模板渲染. 支持 url 解析时产生的异常支持视图处理时产生的异常支持 500 错误时内部产生的异常. 12 / 16

13 2 数据库支持 Python 探针目前支持以下数据库性能监测, 若您站点使用其他类型的数据库 api, 其数据库的性能将不会被采集随着探针的升级, 更多的模块将会支持数据库数据库模块备注 mysql MySQLdb pymysql oracle PostgreSQL ODBC cx_oracle psycopg2 psycopg2ct psycopg2cffi pyodbc Memcached python_memcached bmemcached 13 / 16

14 3 外部调用支持仅支持以下列表中的组件的性能采集, 若您站点使用其他类型的外部调用模块, 其性能数据库将不会被采集随着探针的升级, 更多的模块将会支持 urllib urllib2 urllib3 模块备注 14 / 16

15 五故障与修复 1 探针常见问题 1 探针 log 文件未生成, 如果配置了 log, 但又没有生成 log 文件, 可能有以下原因, 请逐一排查是否配置了探针的配置文件的环境变量, 并正确设置路径读取权限等指定的文件名所在的目录不存在或者该目录下您的应用程序进程的用户无权限写入 python logging 模块的冲突如果 python logging 模块优先初始化了探针 log, 而后监控的应用程序又调用了 logging.config.fileconfig() 函数, 那么将会引发这个问题解决的方案之一是向该函数中传递 disable_existing_loggers=false 参数, 让 logging module 允许存在初始化的 log 2 更新了本地配置, 为什么没有生效? 如果更新本地配置文件, 探针系统不能自动识别, 目前解决方案为 : 重启应用 ( 探针也被重启 ) 15 / 16

16 附加说明该章节对于一些探针的技术点限制特点等进行一些详细说明 1 关于 uwsgi 的说明 --enable-threads,uwsgi 默认情况下, 没有开启多线程的支持, 由于探针基于多线程模式, 所以必须开启此模式, 否则探针无法正常启动如果 uwsgi 使用了选项 threads, 将自动开启选项 --enable-threads --single-interpreter, 默认情况下 uwsgi 为了隔离应用环境, 以便运行多个应用, 在启动的时候会启动子进程来运行某个应用, 而不是在主进程中执行为了更好的适应探针环境请开启这个选项, 开启后不会有其他任何的副作用, 它也是安全而有效的方式 16 / 16

听云平台使用说明

听云平台使用说明 Python 探针用户指南北京基调网络股份有限公司 1 / 32 简述听云 python 探针 ( 也称 Python Agent) 是基于 Python 语言而研发的性能监测工具客户端, 其主要目标为支持 WSGI 协议的 python web 框架理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测, 比如 django tornado flask 等当然其中也包括一些该 web

简述 听云 python 探针 ( 也称 Python Agent) 是基于 Python 语言而研发的性能监测工具客户端, 其主要目标为支持 WSGI 协议的 python web 框架 理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测, 比如 django tornado fla

简述听云 python 探针 ( 也称 Python Agent) 是基于 Python 语言而研发的性能监测工具客户端, 其主要目标为支持 WSGI 协议的 python web 框架理论上基于只要是基于 WSGI 协议的 web 框架都能对其监测, 比如 django tornado fla