@loga：Python的自动日志记录

版本 1.0.0

您发现Python内置的logging模块重复、繁琐且丑陋，您使用它编写的日志与您其他令人赞叹的风格相冲突。loga就是为了帮助您：它自动化无聊的事情，简化复杂的事情，无缝连接到graylog，并在需要时关注隐私和安全。

安装

pip install loga

要使用Graylog支持安装，请执行

pip install loga[graylog]

设置

要开始，导入并实例化主类，最好是在您项目的核心部分。如果您有一个包含多个文件的模块，请在主__init__.py中或在一个名为log.py的文件中进行初始配置，这样您可以轻松导入相同的、已设置好的记录器。

例如，如果您的应用程序名为tester，您可以在tester/__init__.py中添加以下内容

from loga import Loga

# all setup values are optional
loga = Loga(
    facility="tester",  # name of program logging the message
    graylog_address=("0.0.0.0", 9999),  # address for graylog (ip, port)
    do_print=True,  # print each log to console
    do_write=True,  # write each log to file
    logfile="mylog.txt",  # custom path to logfile
    truncation=1000,  # longest possible value in extra data
    private_data={"password"},  # set of sensitive args/kwargs
)

用法

在其他项目部分，您可以使用以下方式访问配置好的记录器实例

from tester import loga

Loga作为装饰器

您可以将@loga用作任何可调用对象（类、类的方法或函数）的装饰器。在类上使用时，它会记录每个方法；在方法和函数上，它会记录调用签名、返回值和错误。loga背后的核心思想是，您可以简单地装饰项目中的每个类，以及任何重要的独立函数，而无需额外的工作，即可获得关于项目内部的综合、标准化的信息。

如果一个装饰过的类中的方法被频繁调用，或者您不需要关注它，您可以使用@loga.ignore来忽略它。此外，还有@loga.errors，它将只记录异常，而不是调用和返回。

让我们通过一个示例用例来说明，创建一个简单的类，该类只乘以两个数字，但前提是提供了密码。我们将忽略无聊的认证系统的日志记录。

@loga
class Multiplier:
    def __init__(self, base):
        self.base = base

    def multiply(self, n, password):
        """
        Multiply by the number given during initialisation--requires password
        """
        self.authenticated = self._do_authentication(password)
        if not self.authenticated:
            raise ValueError("Not authenticated!")
        return self.base * n

    @loga.ignore
    def _do_authentication(self, password):
        """Not exactly Fort Knox"""
        return password == "tOpSeCrEt"

首先，让我们正确使用它，传递我们的秘密密码

mult = Multiplier(50)
result = mult.multiply(50, "tOpSeCrEt")
assert result == 2500  # True

您将在控制台获得一些漂亮的文本

11.05 2018 17:14:54 *Called Multiplier.multiply(n=50, password='******')
11.05 2018 17:14:54 *Returned from Multiplier.multiply(n=50, password='******') with int (2500)

请注意，我们的私有参数password成功被隐藏了，即使我们没有在调用方法时命名该参数。如果您使用了do_write=True，此日志也将出现在您指定的日志文件中，并且密码也被隐藏。

result = mult.multiply(7, "password123")

这里将引发错误，将生成日志，我们将在控制台获得更多信息，包括跟踪信息

11.05 2018 17:19:43 *Called Multiplier.multiply(n=7, password='******')
11.05 2018 17:19:43 *Errored during Multiplier.multiply(n=7, password='******') with ValueError "Not authenticated!"    20 -- see below:
Traceback (most recent call last):
  File "/Users/danny/work/loga/loga/loga.py", line 137, in full_decoration
    response = function(*args, **kwargs)
  File "tester.py", line 13, in multiply
    raise ValueError('Not authenticated!')
ValueError: Not authenticated!

如果您使用的是graypy，您将获得许多额外的功能，例如调用签名的键值对、时间戳、参数、返回值、异常信息等。

自定义消息

当配置loga时，您可以使用自己的消息格式来自动生成的日志。有四个键，每个用于自动日志类型。

loga = Loga(
    called="Log before callable is run",
    returned="Log for return from {call_signature} at {timestamp}",
    returned_none="Log when the return value of the callable is None",
    errored="Log string on exception: {exception_type}",
)


@loga
def test():
    pass

如果您将这些关键字参数中的任何一个传递为None，则将完全抑制该时间的日志。如果您为returned_none没有提供值，则loga将使用您为returned提供的值，或者退回到其默认值。

请注意，在上面的示例中，您可以在日志消息中包含特定的格式字符串。目前支持以下内容：

• call_signature：可调用对象名称及其参数和关键字参数
• callable：装饰对象的__qualname__
• params：传递的参数的逗号分隔键值对
• log_level：与此日志关联的日志级别
• timestamp：记录日志的时间
• couplet：uuid.uuid1()用于调用和返回/错误对
• number_of_params：args + kwargs的总数（以整数形式表示）
• decorated：始终为True

errored日志还支持以下内容：

• exception_type：ValueError、AttributeError等。
• exception_msg：抛出异常的详细信息
• traceback：异常跟踪信息

returned和returned_none日志支持以下内容：

• return_value：可调用对象返回的对象
• return_type：返回对象类型

添加更多此类字符串很简单；如果有其他需要，请提交一个问题。

无装饰器的日志记录

对于手动日志记录，loga提供了类似于logging标准库中日志记录函数的方法：loga.log、loga.debug、loga.info、loga.warning、loga.error和loga.critical。这些方法使用已定义的配置。主方法loga.log接受三个参数

level = 50
msg = "Message to log"
extra = dict(some="data", that="will", be="logged")
loga.log(level, msg, extra)
# console: 11.05 2018 17:36:24 Message to log  50
# extra_data in log file if `do_print` setting is True

loga.debug、loga.info、loga.warning、loga.error和loga.critical是设置日志级别的便利方法。例如：

loga.warning("A message", dict(some="data"))

等同于

loga.log(logging.WARNING, "A message", dict(some="data"))

其中logging.WARNING是从标准库导入的整数常量。

使用loga进行此类日志记录的优势在于，loga将使额外数据更易于阅读，并截断非常长的字符串。更重要的是，您仍然可以获得您已配置的任何额外信息，例如私有数据的模糊化或写入控制台/文件。

方法

您还可以在任何代码位置使用 loga.start() 和 loga.stop() 来启动和停止日志记录，尽管默认情况下，错误日志仍然可以通过。如果您还想抑制错误，可以传递 allow_errors=False。

上下文管理器

您可以使用上下文管理器来抑制日志。默认情况下，这里也允许错误。

with loga.pause(allow_errors=False):
    do_something()

限制

loga 使用 Python 的标准库 (logging) 来生成日志。使用它时有一些需要注意的问题：例如，在传递额外数据时，此额外数据的键名不能与 logging 模块内部使用的某些内部名称冲突（例如 message、args 等）。为了解决这个问题，您将收到一个警告，说明您的数据包含一个无效的键名，并且它将被更改为（例如从 message 更改为 protected_message）。