炼金术日志记录（模拟） - Python

该alog框架提供具有易于使用的默认值和高级用户功能的可调日志记录。的口头禅alog是“尽早并经常记录”。为了实现这个目标，alog可以轻松地在开发/调试时启用详细日志记录，并在生产运行时调整详细程度。

设置

要使用该alog模块，只需安装它pip：

pip install alchemy-logging

通道和级别

框架的主要组件是通道和级别，它们允许在适当的时候启用或禁用每个日志语句。

1. 级别：每个日志记录语句都在特定级别进行。级别提供顺序粒度，允许在代码中放置详细的调试语句，而不会在运行时阻塞日志。级别的顺序及其一般用法如下：

   1. off：完全禁用给定频道
   2. fatal: 发生了致命错误。此语句之后的任何行为都应视为未定义。
   3. error: 发生了不可恢复的错误。除非明确处理错误，否则此语句之后的任何行为都应视为未定义。
   4. warning：出现了一个可恢复的错误情况，服务维护人员应该注意这一点。
   5. info：在中等负载下运行时有价值的高级信息。
   6. trace：用于记录调试代码路径的函数的开始/结束。
   7. debug：函数参数等高级调试语句。
   8. debug1: 高级调试语句。
   9. debug2：中级调试语句，例如计算值。
   10. debug3：低级调试语句，例如循环内的计算值。
   11. debug4：超低级调试语句，例如数据转储和/或多个嵌套循环内的语句。

2. Channels：每个日志记录语句都针对特定的通道。通道相互独立，允许按功能对日志消息进行逻辑分组。通道可以是任何字符串。通道可能具有分配给它的特定级别，或者如果未为其指定特定级别过滤器，则它可以使用配置的默认级别。

使用Channels和Levels的这种组合，您可以微调在不同情况下运行应用程序时启用的日志语句。

用法

配置

import alog

if __name__ == "__main__":
    alog.configure(default_level="info", filters="FOO:debug,BAR:off")

在本例中，通道"FOO"设置为debug电平，通道"BAR"完全禁用，所有其他通道设置为使用INFO电平。

除了上述之外，该configure函数还支持以下参数：

• formatter: 可能是"pretty", "json", 或任何派生自的类AlogFormatterBase
• thread_id: 布尔值，指示是否在日志标头 ( pretty) 或结构 ( json) 中包含唯一线程 ID。
• handler_generator：这允许用户提供自己的输出处理程序并替换将日志消息发送到的标准处理程序stderr。有关详细信息，logging请参阅文档。

记录功能

对于每个日志级别，您可以使用两个函数来创建日志行：标准logging包函数或相应的alog.use_channel(...).<level>函数。前者将始终登录到root频道，而后者则需要通过 指定频道字符串use_channel()。

import alog
import logging

def foo(age):
    alog.use_channel("FOO").debug3(
        "Debug3 line on the FOO channel with an int value %d!", age
    )
    logging.debug("debug line on the MAIN channel")

频道日志

在给定的代码部分中，拥有许多日志语句使用的公共通道通常是有意义的。重新输入频道名称可能很麻烦且容易出错，因此频道日志的概念有助于消除此问题。要创建频道日志，请调用该use_channel函数。这为您提供了通道日志的句柄，该日志具有与顶级日志功能相同的所有标准日志功能alog，但不需要指定通道。例如：

import alog

log = alog.use_channel("FOO")

def foo(age):
    log.info("Hello Logging World! I am %d years old", age)

注意：在这个（python）实现中，这只是一个包装器logging.getLogger()

额外的日志信息

还有几种其他类型的信息alog支持添加到日志记录：

日志代码

这是向记录添加指定代码的所有日志记录函数的可选参数。对于您希望能够以编程方式跟踪的特别引人注目的消息（例如服务器中的每个请求错误摘要），它可能很有用。对 a 的唯一要求log_code是它以 开头<和结尾>。日志代码总是在message. 例如：

ch = alog.use_channel("FOO")
ch.debug("<FOO80349757I>", "Logging is fun!")

字典数据

有时，在记录中记录结构化的键/值对而不是纯文本消息很有用，即使在使用pretty输出格式化程序时也是如此。为此，只需在日志记录函数的参数中使用 adict代替 a 。例如：strmessage

ch = alog.use_channel("FOO")
ch.debug({"foo": "bar"})

在启用格式化程序的dict情况下记录 a 时json，所有键/值对都将作为键/值对添加到顶级message键下。

日志上下文

日志记录最常见的用途之一是在某个代码块执行时记录事件。为了促进这一点，alog有日志上下文的概念。支持的两个主要上下文alog是：

• ContextLog：此上下文管理器START:在上下文开始时记录一条消息，END:在上下文结束时记录一条消息。在上下文内的同一线程中生成的所有消息将具有递增的缩进级别。

import alog

alog.configure("debug2")
log = alog.use_channel("DEMO")

with alog.ContextLog(log.info, "Doing some work"):
    log.debug("Deep in the muck!")

2021-07-29T19:09:03.819422 [DEMO :INFO] BEGIN: Doing some work
2021-07-29T19:09:03.820079 [DEMO :DBUG]   Deep in the muck!
2021-07-29T19:09:03.820178 [DEMO :INFO] END: Doing some work

• ContextTimer：此上下文管理器在上下文开始时启动一个计时器，并在上下文结束时记录一条带有持续时间的消息。

import alog
import time

alog.configure("debug2")
log = alog.use_channel("DEMO")

with alog.ContextTimer(log.info, "Slow work finished in: "):
    log.debug("Starting the slow work")
    time.sleep(1)

2021-07-29T19:12:00.887949 [DEMO :DBUG] Starting the slow work
2021-07-29T19:12:01.890839 [DEMO :INFO] Slow work finished in: 0:00:01.002793

函数装饰器

除了您可能希望范围或时间的任意代码块之外，记录上下文的一个非常常见的用例是提供函数跟踪。为此，alog提供了两个有用的函数装饰器：

• @logged_function: 这个装饰器包装ContextLog并提供了一个START/END范围，其中消息预先填充了函数的名称。

import alog

alog.configure("debug")
log = alog.use_channel("DEMO")

@alog.logged_function(log.trace)
def foo():
    log.debug("This is a test")

foo()

2021-07-29T19:16:40.036119 [DEMO :TRCE] BEGIN: foo()
2021-07-29T19:16:40.036807 [DEMO :DBUG]   This is a test
2021-07-29T19:16:40.036915 [DEMO :TRCE] END: foo()

• @timed_function：这个装饰器包装ContextTimer了整个函数并执行了一个作用域定时器。

import alog
import time

alog.configure("debug")
log = alog.use_channel("DEMO")

@alog.timed_function(log.trace)
def foo():
    log.debug("This is a test")
    time.sleep(1)

foo()

2021-07-29T19:19:47.468428 [DEMO :DBUG] This is a test
2021-07-29T19:19:48.471788 [DEMO :TRCE] 0:00:01.003284