日志控制：Sublime Text的日志插件

此插件为Sublime Text提供用户界面命令，以启用并调整使用Python的内置logging模块的日志输出。日志仅适用于已经使用标准logging模块的插件。

此插件允许用户自定义：

• 如何显示日志消息
• 是否将日志消息保存到文件
• 显示/写入文件的日志消息类型（DEBUG/INFO/WARNING/FATAL消息）。

用户可以使用ctrl+shift+p并在选择所需级别来即时调整日志级别。

使用日志库显示消息与正常print()方法有何不同？

print()通常用于在控制台中向用户显示信息，显示与用户相关的信息。

另一方面，日志消息通常是创建来允许用户（或开发者）了解程序正常流程中的情况。日志消息通常用于回溯，查看随着时间的推移打印的消息，以了解由哪段代码/插件引起的。因此，日志消息应带有时间戳和标识符，以告知消息的来源（哪个插件）。如果用户要解析日志输出，则将这种日志输出格式化相同很有方便。（而不是让每个插件开发者使用自己的日志格式）。

对于所有希望生成日志消息的Python代码（尤其是库），使用logging模块是一种最佳实践。由于SublimeText插件可以被认为是“库”（即它们不是用于直接消费），因此使用Python的logging库可能是输出日志消息的一种适当方式。

用例场景

我开发了这个插件，因为我想要调试自动保存插件的行為。我在多个电脑上打开dropbox中的文件时遇到了问题，这两台电脑都在Sublime Text上打开，并且自动保存都处于开启状态。我想让这个插件在自动保存插件保存文件时临时打印时间戳消息。但是，我不想修改插件以始终打印这条消息——那样会产生太多的消息，充满用户的控制台。

这个包已经演变成一个更通用的日志控制包。除了允许你切换日志开/关和设置日志级别（对于根日志记录器），它还提供了几种方便的方式来配置Python的标准日志系统，并在Sublime Text启动时初始化。

这个插件不是什么

这个插件不是用来从所有控制台输出中获取内容保存到文件中的。这个功能由例如SublimeLog插件提供。

不同之处在于，这个包，即日志控制，专门关注通过标准python日志库进行日志记录。而例如SublimeLog用于将打印到stdout/stderr的消息重定向到文件而不是控制台。

与仅使用print()打印错误消息相比，使用Python标准库提供的适当日志系统提供了一个许多优点。使用Python的标准日志库，库开发人员不必担心是否会产生调试/信息消息会导致用户的控制台消息量过大。开发人员可以产生他/她认为需要的任何数量的日志消息，但将print()的使用保留给开发者实际想要向用户控制台显示消息的情况。库用户（应用程序开发人员）可以将所有日志消息定向到文件中，以保持控制台输出整洁。库用户还可以根据需要（或永远，如果用户喜欢始终看到发生的事情）将日志消息输出到控制台。

这个插件，即日志控制，也不是用来控制用户输入的日志。可以使用Verbose插件或直接通过Sublime Text的log_* API方法直接开启或关闭用户调用的命令和按键。

使用方法

这个包的主要目的是配置和初始化Python的标准日志系统，使用户能够轻松地定制日志系统。下面的“配置”部分将描述配置日志系统的方法。

但是，这个包确实提供了一些方便的命令来动态调整日志：按Ctrl+Shift+p并开始键入“日志”。选择你想要调用的命令。

• "日志：禁用日志" - 将禁用日志记录（通过将logging_root_level设置为非常高的级别）。
• "日志：启用日志" - 将启用日志，如果尚未初始化，将初始化日志系统。
• "日志：切换日志" - 将切换日志的开启和关闭状态。
• "日志：级别 = %级别%" - 将logging_root_level设置为%级别%。
• "日志：重置日志系统" - 将重置日志系统（以防出现错误）。

配置

注意：正如名称所表明的，日志控制只是一个用于控制标准python日志库行为的包。我强烈建议查看日志 – 如何和日志模块文档。这些文档将给你一个关于日志控制如何工作以及日志控制可以和不能做什么的良好印象。

有关如何使用自定义配置文件创建和使用“高级，基于字典”的日志行为的信息，请参阅Python - 记录 - 配置文档。

设置键和默认值 - 概述

"logging_root_level": "INFO",
"logging_persist_changes": false,
"logging_enable_on_startup": true,
"logging_use_basicConfig": false,
"logging_console_enabled": true,
"logging_console_fmt": "%(asctime)s %(levelname)-5s %(name)20s:%(lineno)-4s%(funcName)20s() %(message)s",
"logging_console_datefmt": "%H:%M:%S",
"logging_console_level": "DEBUG",
"logging_file_enabled": false,
"logging_file_fmt": "%(asctime)s %(levelname)-6s - %(name)s:%(lineno)s - %(funcName)s() - %(message)s",
"logging_file_datefmt": "%Y%m%d-%H:%M:%S",
"logging_file_level": "DEBUG",
"logging_file_path": "sublime_output.log",
"logging_file_rotating": true,
"logging_file_clear_on_reset": false
"logging_config_dict_file": null,
"logging_config_dict": null

控制输出的参数

• logging_console_enabled和logging_file_enabled分别控制日志消息是否写入控制台和/或文件。
• logging_console/file_fmt设置控制日志消息如何格式化以输出到控制台和文件。
• logging_console/file_datefmt设置控制控制台和文件输出中时间戳的格式。
• logging_file_path用于指定当logging_file_enabled设置为true时写入日志消息的文件。
• logging_file_rotating可以被设置为true以使用“旋转”日志文件方案。当日志文件超过20MB时，它将被重命名为<logfilename>.log.1，并创建一个新的日志文件（创建多达3个旧日志文件）。有关更多信息，请参阅Python – 记录模块 - RotatingFileHandler。

控制行为的参数

• logging_persist_changes：如果用户设置了记录级别（到DEBUG/INFO等），则在退出后记住此级别。
• logging_enable_on_startup：在启动时启用记录。
• logging_use_basicConfig：可用于确保插件不会重置其他包已初始化的日志系统。

控制打印哪些日志类型（哪个级别）的参数

• logging_root_level控制考虑到的最低严重级别。
• logging_console_level可以增加到只打印至少这个级别的消息到控制台。
• logging_file_level可以增加到只打印至少这个级别的消息到日志文件。

使用高级字典式日志配置的参数

• logging_config_dict_file – 描述高级字典配置的.json或.yaml文件的文件路径。请参阅Python - 记录 - 配置文档。
• logging_config_dict – 也为高级dictConfig配置，但不是将配置字典放在单独的.json文件中，而是将配置日志系统的字典包含在logging_control.sublime-settings文件中。
  

提示：您可以使用以下方式打开用户可编辑的设置文件

Preferences -> Package Settings -> Logging Control -> Settings - User

示例

示例1：您想将所有调试消息打印到日志文件中，但只在控制台中显示最严重的消息

"logging_use_basicConfig": false,
"logging_console_enabled": true,
"logging_file_enabled": true,
"logging_root_level": "DEBUG",
"logging_console_level": "WARNING",     # Only print warning log messages in the console.
"logging_file_level": "DEBUG"           # But write DEBUG messages to the log file.

注意：仅当logging_use_basicConfig设置为false时，才支持使用不同级别控制台和文件输出。此外，如果logging_root_level设置为“INFO”，则即使logging_file_level设置为“DEBUG”，也只会打印“INFO”消息。

使用dictConfig配置的高级示例

场景：您在特定包（foopack）中遇到问题，想打印所有调试和信息日志消息，但不想让控制台或日志文件被其他包的调试日志信息淹没。有几种配置日志系统的方法来实现，唯一的要求是foopack确实使用了Python的标准日志系统

1. 您可以配置foopack使用的logger以发布其日志消息。通常，库将使用与其创建日志消息的包模块名称相匹配的logger，即它将具有logger = logging.getLogger(__name__)。例如，您可以配置foopack的logger为其level=DEBUG并附加一个单独的handler将日志消息打印到控制台或单独的文件。这种方法主要适用于您熟悉foopack的工作方式，并且只对foopack感兴趣。
2. 您可以配置一个仅允许foopack的日志消息通过的filter，并将该filter附加到root logger的handler上。

使用filter和多个handler的第二个解决方案的示例配置

"logging_config_dict": {
  "version": 1,
  "filters": {
    "allow_foopack": {
      "name": "foopack"
    }
  },
  "formatters": {
    "detailed": {
      "format": "%(asctime)s %(levelname)-5s %(name)20s:%(lineno)-4s%(funcName)20s() %(message)s",
      "datefmt": "%Y%m%d-%H:%M:%S"
    },
    "fulldate": {
      "format": "%(asctime)s %(levelname)-5s %(name)s:%(lineno)-4s %(message)s",
      "datefmt": "%Y%m%d-%H:%M:%S"
    },
    "standard": {
      "format": "%(asctime)s %(levelname)-8s %(name)-15s %(message)s",
      "datefmt": "%H:%M:%S"
    }
  },
  "handlers": {
    "custom_tofile": {
      "class": "logging.FileHandler",
      "filters": ["allow_foopack"],
      "filename": "custom_log_output_temp.log",
      "formatter": "fulldate",
      "level": "DEBUG"
    },
    "std_console": {
      "class": "logging.StreamHandler",
      "formatter": "standard",
      "stream": "ext://sys.stdout",
      "level": "WARNING"
    },
    "custom_console": {
      "class": "logging.StreamHandler",
      "filters": ["allow_foopack"],
      "stream": "ext://sys.stdout",
      "formatter": "standard",
      "level": "DEBUG"
    }
  },
  "root": {
    "handlers": ["std_console", "custom_console", "custom_tofile"],
    "level": "DEBUG"
  }
}

正如您所看到的，配置字典很快就变得相当难以管理。在单独的文件中指定日志配置，使用如YAML之类的更易读的格式可能更加方便。您可以使用 logging_config_dict_file 关键字来指定此类外部文件。（必须为YAML或JSON格式）。

有关使用dict-config设置自定义日志系统的更多信息，请参阅此包根目录中的 dictconfig_example.yaml 文件。

键绑定

键绑定可用于为您的常用命令创建键盘快捷键。打开 Default (Platform).sublime-keymap，可以通过以下任一方式打开

Preferences -> Package Settings -> Logging Control -> Key Bindings--User
    Preferences -> Key Bindings--User

然后编辑文件，使其看起来像以下内容

[
    { "keys": ["ctrl+alt+shift+t"], "command": "logging_toggle" },
    { "keys": ["ctrl+alt+shift+e"], "command": "logging_toggle", "args": {"enable": false} },
]

命令列表可以在 logging_control.sublime-commands 中找到（默认的 logging_control.sublime-settings 文件旁边。）

开发者笔记

要使用Package Control创建新版本

1. 在 messages/ 下创建一个文本文件来描述版本更新，并相应更新 messages.json。
2. 使用更高语义版本标记当前修订版为较新版本，并将其标签（和修订版）推送到GitHub

git tag -a 1.2.3 -m "Release 1.2.3"
git push origin --tags