@loggo：Python 3的自动化日志记录

版本 10.1.3

您觉得Python内置的logging模块重复、繁琐且丑陋，而且使用它记录的日志与您原本的风格不符。loggo2就是为了解决这个问题而诞生的：它自动化了枯燥的工作，简化了复杂的工作，轻松连接到graylog，并在需要时关注隐私和安全。

安装

pip install loggo2
# or
python setup.py install

要安装带Graylog支持的版本，请执行以下操作：

pip install loggo2[graylog]

设置

要开始使用，导入并实例化主类，最好放在您项目的核心位置。如果您有一个包含多个文件的模块，请在主__init__.py文件中进行初始配置，或者在一个名为log.py的文件中。这样您就可以轻松导入已经配置好的日志记录器。

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

from loggo2 import Loggo

# all setup values are optional
loggo = Loggo(
    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 loggo

Loggo作为装饰器

您可以将@loggo用作任何可调用对象的装饰器：类、方法或函数。在类中，它会记录每个方法；在方法和函数中，它会记录调用签名、返回值和错误。Loggo背后的核心思想是您可以为项目中的每个类以及任何重要的独立函数简单地添加装饰器，而无需额外的劳动，就可以获得关于项目内部信息的全面、标准化的信息。

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

让我们通过一个简单的示例来展示其用法，创建一个简单的类，用于乘以两个数字，但前提是提供一个密码。我们将忽略对枯燥的认证系统的日志记录。

@loggo
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

    @loggo.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/loggo/loggo/loggo.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，您将获得许多额外的功能，例如调用签名的键值对、时间戳、参数、返回值、异常信息等。

自定义消息

在配置loggo时，您可以使用自己的消息格式来自动生成日志。这里有四个键，每个键对应一种自动记录类型

loggo = Loggo(
    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}",
)


@loggo
def test():
    pass

如果您为任何这些关键字参数传递了None，则将完全抑制该时间的日志。如果您没有为returned_none提供值，loggo将使用您为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：异常跟踪信息

并且支持返回和返回无的日志

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

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

无装饰器的日志记录

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

level = 50
msg = "Message to log"
extra = dict(some="data", that="will", be="logged")
loggo.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

方法loggo.debug、loggo.info、loggo.warning、loggo.error和loggo.critical是设置日志级别的便捷方法。例如，

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

相当于

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

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

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

方法

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

上下文管理器

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

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

贡献

样式

样式为Black，但有以下例外和额外严格性

• 最大行长度为110
• 除非使用# type: ignore忽略，否则不应使用类型的注释语法。也就是说，这样写

  def hello() -> str:
      return_value: str = 'hello'
      return return_value
  

  而不是这样写

  def hello(): # type: () -> str
      return_value = 'hello'  # type: str
      return return_value
  

创建拉取请求

问题、功能请求和代码贡献都受欢迎。按照以下步骤创建拉取请求

1. 叉/克隆存储库。

2. 安装依赖项（您可能需要首先创建虚拟环境，使用您首选的方法）。

   pip install -e .[dev]
   

3. 安装pre-commit钩子

   pre-commit install
   

4. 在做出更改并编写测试后，请确保测试通过

   pytest --cov
   

5. 提交、推送并创建PR。

版本升级

loggo遵循语义版本控制，理想情况下通过bump2version实用程序。使用pip安装它

pip install bump2version

每次需要升级版本时，在项目根目录中执行

bump2version (major | minor | patch)
git push <remote> <branch> --follow-tags 

限制

loggo2使用Python的标准库（logging）生成日志。使用它时有一些需要注意的问题：例如，在可以传递的额外数据方面，此类额外数据的键名不能与logging模块内部使用的某些内部名称冲突（message、args等）。为了解决这个问题，您会收到一个警告，表明您数据中的键名不正确，并且它将被更改（例如，从message到protected_message）。