Loggate

支持日志元数据和发送到 Grafana Loki 的复杂日志系统。这个库支持线程和 asyncio 模块。

简单的 stdout/stderr 彩色输出

一个例子胜过千言万语。

from loggate import setup_logging, get_logger

setup_logging(level='DEBUG')
logger = get_logger('component', meta={'version': '1.0.0'})

logger.debug('Loading resources for the component')
logger.info('Initialize of the component')
logger.warning('The component is not ready')
logger.error('The component failed.',
             meta={'inputs': {'A': 1, 'B': 2}})
logger.critical('The component unexpected failed.',
                meta={'attrs': {'A': 1, 'B': 2}})

控制台输出

异常

from loggate import setup_logging, get_logger

setup_logging()
logger = get_logger('component', meta={'version': '1.0.0'})

try:
    raise Exception('Some error')
except Exception as ex:
    logger.error('The component failed.', exc_info=True)

控制台输出

高级配置

Loggate 支持类似于 logging.config 的声明式配置。但也支持配置文件。这意味着我们可以声明多个日志配置文件并在它们之间切换。默认配置文件名为 default。

我们可以使用 yaml 文件作为配置文件（见下文）

profiles:
  default:                             
    # Default profile
    filters:
      warning:                          
        # This is a filter for stdout logger, that enable only logs with level lower than WARNING. 
        # For logs with WARNING and higher we use stderr logger. 
        class: loggate.LowerLogLevelFilter
        level: WARNING

    formatters:
      colored:
        # This is stdout/sterr formatter. 
        class: loggate.LogColorFormatter
      loki:
        # This is formatter of loki messages.
        class: loggate.loki.LokiLogFormatter

    handlers:
      stdout:
        # This is a stdout handler
        class: logging.StreamHandler
        stream: ext://sys.stdout
        formatter: colored
        filters:
          - warning
      stderr:
        # This is a stderr handler
        class: logging.StreamHandler
        stream: ext://sys.stderr
        formatter: colored
        level: WARNING        
      loki:
        # This is a loki handler
        class: loggate.loki.LokiThreadHandler  # for asyncio use loggate.loki.LokiHandler       
        formatter: loki
        max_queue_size: 1000        # Default is 0 = unlimit
        # send_retry:  [5, 5, 10, 10, 30, 30, 60, 60, 120]
        urls:
          - "http://loki1:3100/loki/api/v1/push"
          - "http://loki2:3100/loki/api/v1/push"
          - "http://loki3:3100/loki/api/v1/push"
        meta:
          # loggate handlers accept metadata as well. Standard logging handlers do not!
          stage: dev
          ip: 192.168.1.10
                  

    loggers:
        root:          
          level: INFO
          handlers:
            - stdout
            - stderr        
            - loki
        'urllib3.connectionpool': 
          level: WARNING

import yaml
from loggate import setup_logging, get_logger


def get_yaml(filename):
    with open(filename, 'r+') as fd:
        return yaml.safe_load(fd)


schema = get_yaml('test.yaml')
setup_logging(profiles=schema.get('profiles'))

logger = get_logger('component')

logger.debug('Loading resources for the component')
logger.info('Initialize of the component')
logger.warning('The component is not ready')

控制台输出与上面相同，但现在我们将日志也发送到 Loki。

Loki 输出

描述

方法

• get_logger

  • name - 返回具有此名称的记录器。空名称返回根记录器。
  • meta - 元数据（字典），仅由该记录器发送。

• getLogger - get_logger 的别名

• setup_logging - 应用程序日志的初始化设置。

  • profiles - 日志配置文件（dict）的配置。当我们不设置此参数时，应用程序将使用预定义的配置文件，其日志级别为 INFO（此级别可以通过参数 level 设置）。
  • default_profile - 默认配置文件的名称（默认：default）
  • level - 当应用程序使用预定义配置文件时，这是一个特殊参数（默认 INFO）。

过滤器

类 loggate.LowerLogLevelFilter

此过滤器会过滤掉所有高于 level 的日志。

• level - 日志级别

格式化程序

类 loggate.LogColorFormatter

用于 stdout/stderr 的彩色格式化程序。

• fmt - 消息格式（默认：%(LEVEL_COLOR)s%(asctime)s\t [%(levelname)s] %(name)s:%(COLOR_RESET)s %(message)s）
• datefmt - 日期时间格式（默认：%Y-%m-%d %H:%M:%S）
• style - 模板风格（默认：%）
• validate - 验证输入格式（默认：True）
• INDENTATION_TRACEBACK - 默认：\t\t\t
• INDENTATION_METADATA - 默认：\t\t\t\t
• COLOR_DEBUG，...，COLOR_CRITICAL - 设置此级别的颜色（例如 \x1b[1;31m，见 更多颜色）。
• COLOR_METADATA - 设置元数据颜色
• COLOR_TRACEBACK - 设置跟踪颜色
• COLOR_... - 设置自定义颜色

类 loggate.loki.LokiLogFormatter

这是一个特殊的 Loki 格式化程序，它将日志记录转换为 JSON。

处理器

类 loggate.loki.LokiHandler

此处理器将日志记录发送到 Loki 服务器。这是一个阻塞的处理器实现。这意味着，当我们调用日志方法（debug，... critical）时，消息是在同一线程中发送的。我们应仅在具有大量开销的其他方式的小脚本中使用此功能。

• level - 此处理器仅发送等于或高于此日志级别的日志记录（默认：所有 = logging.NOTSET）。
• urls - Loki 入口点的列表。
• strategy - 部署策略（默认：random）。
  • random - 在开始时，处理器选择随机的 Loki 服务器，其他服务器作为后备。
  • fallbacks - 处理器使用第一个 Loki 服务器，其他服务器作为后备。
  • all - 处理器将日志记录发送到所有 Loki 服务器。
• auth - Loki 认证，包含两个项目的列表（username，password）。
• timeout - 单次投递尝试的超时时间（默认：5s）。
• ssl_verify - 启用 SSL 验证（默认：True）。
• max_queue_size - 发送队列的大小。默认为 0 = 无限制。特权消息的极限是 max_queue_size 的 110%。
• send_retry - 以逗号分隔的秒数列表用于重发。列表中的最后一项用作所有其他发送的默认值。
• loki_tags - 发送到 Loki 服务器作为标签的元数据键列表（默认：[logger，level]）。
• meta - 元数据（dict），仅由此处理器发送。

类 loggate.loki.LokiAsyncioHandler

这是 LokiHandler 的非阻塞扩展。我们注册额外的 asyncio 任务以将消息发送到 Loki 服务器。参数与 loggate.loki.LokiHandler 相同。此处理器默认使用 urllib.requests 模块（可选 aiohttp）。不幸的是，urllib.requests 模块不支持 asyncio，这意味着发送本身是阻塞的。loggate.loki.Loki AsyncioHandler 可以使用可选依赖项 aiohttp 进行非阻塞发送。

类 loggate.loki.LokiThreadHandler

这是 LokiHandler 的非阻塞扩展。我们注册并启动额外的线程以将消息发送到 Loki 服务器。参数与 loggate.loki.LokiHandler 相同。

配置文件

配置文件的结构（setup_logging 的 profiles 参数）。

<profile_name>:
  
  filters:
    <filter_name>:
      class: <filter_class>
      <filter_attribute_name>: <filter_attribute_value>
  
  formatters:
    <formatter_name>:
      class: <formatter_class>
      <formatter_attribute_name>: <formatter_attribute_value>
  
  handlers:
    <handler_name>:
      class: <handler_class>
      <handler_attribute_name>: <handler_attribute_value>

  loggers:
    <logger_name>|root:   # definition of root logger
      level: <log_level>
      handlers: 
        - <name_of_handler>|<definition_of_handler>
      disabled: True|False    # default: False
      propagate: True|False   # default: True
      meta: <logger_metadata>