cherrypy._日志记录模块

简单配置

尽管CherryPy使用 Python logging module ，所以简单的日志记录很简单，但是复杂的日志记录仍然是可能的。“简单”日志记录意味着您可以记录到屏幕(即控制台/标准输出)或一个文件，并且您可以很容易地拥有单独的错误和访问日志文件。

以下是简化的日志记录设置。您可以通过在配置文件或字典中添加行来使用它们。您应该在全局级别或每个应用程序(见下文)设置这些设置，但通常不能同时设置这两个设置。

• log.screen ：将其设置为True可将“ERROR”和“ACCESS”消息打印到标准输出。

• log.access_file ：将其设置为要写入“访问”消息的绝对文件名。

• log.error_file ：将其设置为要写入“错误”消息的绝对文件名。

许多事件都是自动记录的；若要记录您自己的应用程序事件，请调用 cherrypy.log() 。

架构

单独的作用域

CherryPy在全局层和应用层都提供日志管理器。这意味着您可以为整个站点设置一组日志记录规则，并为每个应用程序设置另一组特定的规则。全局日志管理器位于 cherrypy.log() ，每个应用程序的日志管理器位于 app.log 。如果您在请求中，则可以从以下位置访问后者 cherrypy.request.app.log ；如果您在请求之外，则必须获取对 app ：或者是的返回值 tree.mount() 或者，如果您使用 quickstart() 取而代之的是，VIA cherrypy.tree.apps['/'] 。

默认情况下，全局日志命名为“cherrypy.error”和“cherrypy.access”，应用程序日志命名为“cherrypy.error.2378745”和“cherrypy.access.2378745”(编号为Application对象的id)。这意味着应用程序将“泡沫”记录到站点日志中，因此如果您的应用程序没有日志处理程序，站点级别的处理程序仍将记录消息。

错误与访问

每个日志管理器都处理“访问”消息(每个HTTP请求一个)和“错误”消息(其他所有消息)。请注意，“错误”日志不仅仅是针对错误的！访问消息的格式是高度形式化的，但错误日志不是这样的--它从各种来源接收消息(包括完整的错误回溯，如果启用的话)。

如果要将访问日志和错误日志记录到同一源，则精心编制的错误消息可能会复制访问日志消息，如CWE-117中所述。在这种情况下，应用程序开发人员有责任在使用CherryPy的log()功能之前手动转义数据，否则他们可能会创建易受CWE-117攻击的应用程序。这可以通过使用自定义处理程序转义任何特殊字符来实现，并按如下所述进行附加。

自定义处理程序

上面的简单设置通过操作Python的标准来实现 logging 模块。因此，当您需要更复杂的功能时，可以充分利用标准模块的全部功能。您可以借用或创建自定义处理程序、格式、过滤器等。下面是一个跳过标准FileHandler而改用RotatingFileHandler的示例：

#python
log = app.log

# Remove the default FileHandlers if present.
log.error_file = ""
log.access_file = ""

maxBytes = getattr(log, "rot_maxBytes", 10000000)
backupCount = getattr(log, "rot_backupCount", 1000)

# Make a new RotatingFileHandler for the error log.
fname = getattr(log, "rot_error_file", "error.log")
h = handlers.RotatingFileHandler(fname, 'a', maxBytes, backupCount)
h.setLevel(DEBUG)
h.setFormatter(_cplogging.logfmt)
log.error_log.addHandler(h)

# Make a new RotatingFileHandler for the access log.
fname = getattr(log, "rot_access_file", "access.log")
h = handlers.RotatingFileHandler(fname, 'a', maxBytes, backupCount)
h.setLevel(DEBUG)
h.setFormatter(_cplogging.logfmt)
log.access_log.addHandler(h)

这个 rot_* 属性直接从应用程序日志对象中提取。因为“log.*”配置条目只是在日志对象上设置属性，所以您可以将自定义属性添加到您的核心内容中。请注意，使用这些处理程序“代替”上面概述的默认简单处理程序(例如，不要设置“log.error_file”配置项)。

class cherrypy._cplogging.LazyRfc3339UtcTime

基类：object

class cherrypy._cplogging.LogManager(appid=None, logger_root='cherrypy')

基类：object

用于帮助简单和高级日志记录的对象。

cherrypy.log 是此类的实例。

_add_builtin_file_handler(log, fname)

_get_builtin_handler(log, key)

_set_file_handler(log, filename)

_set_screen_handler(log, enable, stream=None)

_set_wsgi_handler(log, enable)

access()

写入访问日志(采用Apache/NCSA组合日志格式)。

请参阅 apache documentation 有关格式详细信息，请参阅。

CherryPy会自动为您调用此功能。请注意，没有参数；它本身从以下位置收集数据 cherrypy.request 。

与Apache在2.0.46中开始的操作一样，%r中的不可打印字符和其他特殊字符(我们将其扩展到所有部分)使用xhh序列进行转义，其中hh表示原始字节的十六进制表示。此规则的例外是“和，它们通过添加反斜杠进行转义，以及所有空格字符，它们以其C样式表示法(n、t等)编写。

property access_file

self.access_log的文件名。

如果您将其设置为字符串，它将为您添加适当的FileHandler。如果将其设置为 None 或 '' ，它将删除处理程序。

access_log = None

实际的 logging.Logger 实例用于访问消息。

access_log_format = '{h} {l} {u} {t} "{r}" {s} {b} "{f}" "{a}"'

appid = None

拥有此日志管理器的应用程序对象的id()。如果这是全局日志管理器，则APPID为NONE。

error(msg='', context='', severity=20, traceback=False)

写下给定的 msg 添加到错误日志中。

这不仅仅是为了出错！应用程序可以随时调用它来记录特定于应用程序的信息。

如果 traceback 为True，则当前异常(如果有)的回溯将追加到 msg 。

property error_file

self.error_log的文件名。

如果您将其设置为字符串，它将为您添加适当的FileHandler。如果将其设置为 None 或 '' ，它将删除处理程序。

error_log = None

实际的 logging.Logger 实例以获取错误消息。

logger_root = None

“顶级”记录器名称。

此字符串将用作记录器名称中的第一个段。默认值为“cherrypy”，例如，在这种情况下，记录器名称的格式为：：

cherrypy.error.<appid>
cherrypy.access.<appid>

reopen_files()

关闭并重新打开所有文件处理程序。

property screen

打开或关闭stderr/stdout日志记录。

如果将其设置为True，它将为您添加适当的StreamHandler。如果将其设置为false，则将删除处理程序。

time()

立即以Apache通用日志格式(无时区)返回()。

property wsgi

将错误写入wsgi.error。

如果将其设置为True，它将添加相应的 WSGIErrorHandler 对您而言(它会将错误写入 wsgi.errors )。如果将其设置为false，则将删除处理程序。

class cherrypy._cplogging.NullHandler(level=0)

基类：logging.Handler

用于使logging.lastResort处理程序静默的无操作日志记录处理程序。

createLock()

获取用于序列化对底层I/O的访问的线程锁。

emit(record)

不惜一切代价实际记录指定的日志记录。

此版本旨在由子类实现，因此会引发NotImplementedError。

handle(record)

有条件地发出指定的日志记录。

排放取决于可能已添加到处理程序的过滤器。使用I/O线程锁的获取/释放包装记录的实际发射。返回过滤是否通过排放记录。

class cherrypy._cplogging.WSGIErrorHandler(level=0)

基类：logging.Handler

将日志记录写入环境的处理程序类 ['wsgi.errors'] 。

emit(record)

发出一张唱片。

flush()

冲洗溪流。