记录应用错误

0.3 新版功能.

应用故障,服务器故障。早晚你会在产品中看见异常。即使你的代码是 100% 正确的, 你仍然会不时看见异常。为什么?因为涉及的所有一切都会出现故障。这里给出一些 完美正确的代码导致服务器错误的情况:

  • 客户端在应用读取到达数据时,提前终止请求
  • 数据库服务器超载,并无法处理查询
  • 文件系统满了
  • 硬盘损坏
  • 后端服务器超载
  • 你所用的库出现程序错误
  • 服务器的网络连接或其它系统故障

而且这只是你可能面对的问题的简单情形。那么,我们应该怎么处理这一系列问题? 默认情况下,如果你的应用在以生产模式运行, Flask 会显示一个非常简单的页面并 记录异常到 logger

但是你还可以做些别的,我们会介绍一些更好的设置来应对错误。

错误邮件

如果你的应用在生产模式下运行(会在你的服务器上做),默认情况下,你不会看见 任何日志消息。为什么会这样?Flask 试图实现一个零配置框架。如果没有配置,日 志会存放在哪?猜测不是个好主意,因为它猜测的位置可能不是一个用户有权创建日 志文件的地方。而且,对于大多数小型应用,不会有人关注日志。

事实上,我现在向你保证,如果你给应用错误配置一个日志文件,你将永远不会去看 它,除非在调试问题时用户向你报告。你需要的应是异常发生时的邮件,然后你会得 到一个警报,并做些什么。

Flask 使用 Python 内置的日志系统,而且它确实向你发送你可能需要的错误邮件。 这里给出你如何配置 Flask 日志记录器向你发送报告异常的邮件:

ADMINS = ['yourname@example.com']
if not app.debug:
    import logging
    from logging.handlers import SMTPHandler
    mail_handler = SMTPHandler('127.0.0.1',
                               'server-error@example.com',
                               ADMINS, 'YourApplication Failed')
    mail_handler.setLevel(logging.ERROR)
    app.logger.addHandler(mail_handler)

那么刚刚发生了什么?我们创建了一个新的 SMTPHandler 来用监听 127.0.0.1 的邮件服务器 向所有的 ADMINS 发送发件人为 server-error@example.com ,主题 为 “YourApplication Failed” 的邮件。如果你的邮件服务器需要凭证,这些功能也 被提供了。详情请见 SMTPHandler 的文档。

我们同样告诉处理程序只发送错误和更重要的消息。因为我们的确不想收到警告或是 其它没用的,每次请求处理都会发生的日志邮件。

你在生产环境中运行它之前,请参阅 控制日志格式 来向错误邮件中置放更多的 信息。这会让你少走弯路。

记录到文件

即便你收到了邮件,你可能还是想记录警告。当调试问题的时候,收集更多的信息是个 好主意。请注意 Flask 核心系统本身不会发出任何警告,所以在古怪的事情发生时发 出警告是你的责任。

在日志系统的方框外提供了一些处理程序,但它们对记录基本错误并不是都有用。最让人 感兴趣的可能是下面的几个:

  • FileHandler - 在文件系统上记录日志
  • RotatingFileHandler - 在文件系统上记录日志, 并且当消息达到一定数目时,会滚动记录
  • NTEventLogHandler - 记录到 Windows 系统中的系 统事件日志。如果你在 Windows 上做开发,这就是你想要用的。
  • SysLogHandler - 发送日志到 Unix 的系统日志

当你选择了日志处理程序,像前面对 SMTP 处理程序做的那样,只要确保使用一个低级 的设置(我推荐 WARNING ):

if not app.debug:
    import logging
    from themodule import TheHandlerYouWant
    file_handler = TheHandlerYouWant(...)
    file_handler.setLevel(logging.WARNING)
    app.logger.addHandler(file_handler)

控制日志格式

默认情况下,错误处理只会把消息字符串记录到文件或邮件发送给你。一个日志记 录应存储更多的信息,这使得配置你的日志记录器包含那些信息很重要,如此你会 对错误发生的原因,还有更重要的——错误在哪发生,有更好的了解。

格式可以从一个格式化字符串实例化。注意回溯(tracebacks)会被自动加入到日 志条目后,你不需要在日志格式的格式化字符串中这么做。

这里有一些配置实例:

邮件

from logging import Formatter
mail_handler.setFormatter(Formatter('''
Message type:       %(levelname)s
Location:           %(pathname)s:%(lineno)d
Module:             %(module)s
Function:           %(funcName)s
Time:               %(asctime)s

Message:

%(message)s
'''))

日志文件

from logging import Formatter
file_handler.setFormatter(Formatter(
    '%(asctime)s %(levelname)s: %(message)s '
    '[in %(pathname)s:%(lineno)d]'
))

复杂日志格式

这里给出一个用于格式化字符串的格式变量列表。注意这个列表并不完整,完整的列 表请翻阅 logging 包的官方文档。

格式 描述
%(levelname)s 消息文本的记录等级 ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
%(pathname)s 发起日志记录调用的源文件的完整路径(如果可用)
%(filename)s 路径中的文件名部分
%(module)s 模块(文件名的名称部分)
%(funcName)s 包含日志调用的函数名
%(lineno)d 日志记录调用所在的源文件行的行号(如果可用)
%(asctime)s LogRecord 创建时的人类可读的时间。默认情况下,格 式为 "2003-07-08 16:49:45,896" (逗号后的数字 时间的毫秒部分)。这可以通过继承 :class:~logging.Formatter,并 重载 formatTime() 改变。
%(message)s 记录的消息,视为 msg % args

如果你想深度定制日志格式,你可以继承 FormatterFormatter 有三个需要关注的方法:

format():
处理实际上的格式。需要一个 LogRecord 对象作为参数,并
必须返回一个格式化字符串。
formatTime():
控制 asctime 格式。如果你需要不同的时间格式,可以重载这个函数。
formatException()
控制异常的格式。需要一个 exc_info 元组作为参数,并必须返 回一个字符串。默认的通常足够好,你不需要重载它。

更多信息请见其官方文档。

其它的库

至此,我们只配置了应用自己建立的日志记录器。其它的库也可以记录它们。例如, SQLAlchemy 在它的核心中大量地使用日志。而在 logging 包中有一个方法 可以一次性配置所有的日志记录器,我不推荐使用它。可能存在一种情况,当你想 要在同一个 Python 解释器中并排运行多个独立的应用时,则不可能对它们的日志 记录器做不同的设置。

作为替代,我推荐你找出你有兴趣的日志记录器,用 getLogger() 函数来获取日志记录器,并且遍历它们来附加处理程序:

from logging import getLogger
loggers = [app.logger, getLogger('sqlalchemy'),
           getLogger('otherlibrary')]
for logger in loggers:
    logger.addHandler(mail_handler)
    logger.addHandler(file_handler)

调试应用错误

对于生产应用,按照 记录应用错误 中的描述来配置你应用的日志记录和 通知。这个章节讲述了调试部署配置和深入一个功能强大的 Python 调试器的要点。

有疑问时,手动运行

在配置你的应用到生产环境时时遇到了问题?如果你拥有主机的 shell 权限,验证你 是否可以在部署环境中手动用 shell 运行你的应用。确保在同一用户账户下运行配置 好的部署来解决权限问题。你可以使用 Flask 内置的开发服务器并设置 debug=True , 这在捕获配置问题的时候非常有效,但是 请确保在可控环境下临时地这么做。 不要 在生产环境中使用 debug=True 运行。

调试器操作

为了深入跟踪代码的执行,Flask 提供了一个方框外的调试器(见 调试模式 )。 如果你想用其它的 Python 调试器,请注意相互的调试器接口。你需要设置下面的参数来 使用你中意的调试器:

  • debug - 是否开启调试模式并捕获异常
  • use_debugger - 是否使用内部的 Flask 调试器
  • use_reloader - 是否在异常时重新载入并创建子进程

debug 必须为 True (即异常必须被捕获)来允许其它的两个选项设置为任何值。

如果你使用 Aptana/Eclipse 来调试,你会需要把 use_debuggeruser_reloader 都设置为 False 。

一个可能有用的配置模式就是在你的 config.yaml 中设置为如下(当然,自行更改为适用 你应用的):

FLASK:
    DEBUG: True
    DEBUG_WITH_APTANA: True

然后在你应用的入口( main.py ),你可以写入下面的内容:

if __name__ == "__main__":
    # To allow aptana to receive errors, set use_debugger=False
    app = create_app(config="config.yaml")

    if app.debug: use_debugger = True
    try:
        # Disable Flask's debugger if external debugger is requested
        use_debugger = not(app.config.get('DEBUG_WITH_APTANA'))
    except:
        pass
    app.run(use_debugger=use_debugger, debug=app.debug,
            use_reloader=use_debugger, host='0.0.0.0')