日志记录

Logging 模块提供了一种方法来记录计算的历史和进度，作为事件日志。事件是通过在源代码中插入日志记录语句创建的，例如

@warn "Abandon printf debugging, all ye who enter here!"
┌ Warning: Abandon printf debugging, all ye who enter here!
└ @ Main REPL[1]:1

该系统提供了比在源代码中散布 println() 调用更多的优势。首先，它允许您控制消息的可见性和呈现方式，而无需编辑源代码。例如，与上面的 @warn 相比

@debug "The sum of some values $(sum(rand(100)))"

默认情况下不会产生任何输出。此外，将这样的调试语句保留在源代码中非常便宜，因为如果稍后会被忽略，该系统会避免评估消息。在这种情况下，除非启用了调试日志记录，否则 sum(rand(100)) 和相关的字符串处理永远不会执行。

其次，日志记录工具允许您将任意数据作为一组键值对附加到每个事件。这允许您捕获局部变量和其他程序状态以供以后分析。例如，要将局部数组变量 A 和向量 v 的总和作为键 s 附加，您可以使用

A = ones(Int, 4, 4)
v = ones(100)
@info "Some variables"  A  s=sum(v)

# output
┌ Info: Some variables
│   A =
│    4×4 Matrix{Int64}:
│     1  1  1  1
│     1  1  1  1
│     1  1  1  1
│     1  1  1  1
└   s = 100.0

所有日志记录宏 @debug、@info、@warn 和 @error 共享一些共同的功能，这些功能在更通用宏 @logmsg 的文档中进行了详细描述。

日志事件结构

每个事件都会生成几部分数据，一些由用户提供，一些自动提取。让我们先检查一下用户定义的数据

• 日志级别是消息的一个广泛类别，用于早期过滤。有几个标准级别，类型为 LogLevel；用户定义的级别也是可能的。每个级别的用途都不同

  • Logging.Debug（日志级别 -1000）是供程序开发者使用的信息。这些事件默认情况下是禁用的。
  • Logging.Info（日志级别 0）用于向用户提供一般信息。可以将其视为直接使用 println 的替代方案。
  • Logging.Warn（日志级别 1000）表示某些内容出错，可能需要采取措施，但目前程序仍在工作。
  • Logging.Error（日志级别 2000）表示某些内容出错，并且不太可能恢复，至少对于代码的这一部分而言是这样。通常，此日志级别是不必要的，因为抛出异常可以传达所有必要的信息。

• 消息是一个描述事件的对象。按照惯例，作为消息传递的 AbstractString 被认为是 markdown 格式。其他类型将使用 print(io, obj) 或 string(obj) 用于基于文本的输出，并可能使用 show(io,mime,obj) 用于安装的日志记录器中使用的其他多媒体显示。

• 可选的键值对允许将任意数据附加到每个事件。一些键具有约定意义，可以影响事件的解释方式（请参阅 @logmsg）。

系统还会为每个事件生成一些标准信息

• 扩展日志记录宏的模块。
• 源代码中日志记录宏所在的文件和行。
• 一个消息id，它是日志记录宏出现的源代码语句的唯一固定标识符。即使文件源代码发生更改，只要日志记录语句本身保持不变，此标识符也旨在保持相当稳定。
• 事件的组，默认情况下设置为文件的基名，不带扩展名。这可以用于将消息分组到比日志级别更细的类别中（例如，所有弃用警告的组都是 :depwarn），或跨模块或模块内进行逻辑分组。

请注意，一些有用的信息（例如事件时间）默认情况下不包含在内。这是因为提取此类信息可能代价高昂，并且当前日志记录器也可以动态访问此类信息。定义一个 自定义日志记录器 以根据需要使用时间、回溯、全局变量的值和其他有用信息来扩充事件数据非常简单。

处理日志事件

如您在示例中所见，日志记录语句没有提及日志事件的去向或如何处理。这是系统可组合且适合并发使用的关键设计特性。它通过分离两个不同的关注点来实现这一点

• 创建日志事件是模块作者的关注点，他们需要决定在何处触发事件以及包含哪些信息。
• 处理日志事件——即显示、过滤、聚合和记录——是应用程序作者的关注点，他们需要将多个模块组合成一个协作应用程序。

日志记录器

事件的处理由日志记录器执行，日志记录器是第一个看到事件的用户可配置代码。所有日志记录器都必须是 AbstractLogger 的子类型。

当触发事件时，会通过查找具有全局日志记录器作为回退的任务本地日志记录器来找到相应的日志记录器。这里的想法是，应用程序代码知道如何处理日志事件，并且存在于调用堆栈的顶部某个位置。因此，我们应该向上查找调用堆栈以发现日志记录器——也就是说，日志记录器应该是动态作用域的。（这与日志记录框架形成对比，在日志记录框架中，日志记录器是词法作用域的；由模块作者显式提供或作为简单的全局变量。在这样的系统中，在组合来自多个模块的功能时，控制日志记录很麻烦。）

可以使用 global_logger 设置全局日志记录器，并使用 with_logger 控制任务本地日志记录器。新生成的子任务会继承父任务的日志记录器。

库提供了三种日志记录器类型。 ConsoleLogger 是您在启动 REPL 时看到的默认日志记录器。它以可读的文本格式显示事件，并尝试提供对格式和过滤的简单但用户友好的控制。 NullLogger 是一种方便的方法，用于在必要时丢弃所有消息；它是 devnull 流的日志记录等效项。 SimpleLogger 是一个非常简单的文本格式化日志记录器，主要用于调试日志记录系统本身。

自定义日志记录器应附带对 参考部分 中描述的函数的重载。

早期过滤和消息处理

当事件发生时，会进行一些早期过滤步骤，以避免生成会被丢弃的消息。

1. 消息日志级别会与全局最小级别进行检查（通过 disable_logging 设置）。这是一个粗略但极其廉价的全局设置。
2. 查找当前的日志记录器状态，并将消息级别与日志记录器的缓存最小级别进行检查，该级别可以通过调用 Logging.min_enabled_level 找到。此行为可以通过环境变量覆盖（稍后详细介绍）。
3. 调用 Logging.shouldlog 函数，该函数使用当前日志记录器，并传入一些最少的信息（级别、模块、组、ID），这些信息可以静态计算。最有用的是，shouldlog 传递了一个事件 id，可用于基于缓存的谓词尽早丢弃事件。

如果所有这些检查都通过，则完整评估消息和键值对，并通过 Logging.handle_message 函数传递给当前日志记录器。handle_message() 可以根据需要执行额外的过滤，并将事件显示到屏幕上、保存到文件等。

在生成日志事件期间发生的异常默认情况下会被捕获并记录。这可以防止单个损坏的事件导致应用程序崩溃，这在生产系统中启用很少使用的调试事件时非常有用。此行为可以通过扩展 Logging.catch_exceptions 为每个日志记录器类型自定义。

测试日志事件

日志事件是运行正常代码的副作用，但您可能会发现自己希望测试特定的信息消息和警告。Test 模块提供了一个 @test_logs 宏，可用于对日志事件流进行模式匹配。

环境变量

消息过滤可以通过 JULIA_DEBUG 环境变量进行影响，并作为一种启用文件或模块调试日志记录的简单方法。使用 JULIA_DEBUG=loading 加载 julia 将激活 loading.jl 中的 @debug 日志消息。例如，在 Linux shell 中

$ JULIA_DEBUG=loading julia -e 'using OhMyREPL'
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji due to it containing an invalid cache header
└ @ Base loading.jl:1328
[ Info: Recompiling stale cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji for module OhMyREPL
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/Tokenize.ji due to it containing an invalid cache header
└ @ Base loading.jl:1328
...

在 Windows 上，可以通过在 CMD 中首先运行 set JULIA_DEBUG="loading" 以及在 Powershell 中运行 $env:JULIA_DEBUG="loading" 来实现相同的效果。

类似地，环境变量可用于启用模块（例如 Pkg）或模块根（请参阅 Base.moduleroot）的调试日志记录。要启用所有调试日志记录，请使用特殊值 all。

要在 REPL 中打开调试日志记录，请将 ENV["JULIA_DEBUG"] 设置为感兴趣的模块的名称。在 REPL 中定义的函数属于模块 Main；可以像这样启用它们的日志记录

julia> foo() = @debug "foo"
foo (generic function with 1 method)

julia> foo()

julia> ENV["JULIA_DEBUG"] = Main
Main

julia> foo()
┌ Debug: foo
└ @ Main REPL[1]:1

使用逗号分隔符为多个模块启用调试：JULIA_DEBUG=loading,Main。

示例

示例：将日志事件写入文件

有时将日志事件写入文件可能很有用。以下是如何使用任务本地和全局日志记录器将信息写入文本文件的示例。

# Load the logging module
julia> using Logging

# Open a textfile for writing
julia> io = open("log.txt", "w+")
IOStream(<file log.txt>)

# Create a simple logger
julia> logger = SimpleLogger(io)
SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())

# Log a task-specific message
julia> with_logger(logger) do
           @info("a context specific log message")
       end

# Write all buffered messages to the file
julia> flush(io)

# Set the global logger to logger
julia> global_logger(logger)
SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())

# This message will now also be written to the file
julia> @info("a global log message")

# Close the file
julia> close(io)

示例：启用调试级别消息

以下是如何创建一个 ConsoleLogger 的示例，该日志记录器允许通过任何日志级别高于或等于 Logging.Debug 的消息。

julia> using Logging

# Create a ConsoleLogger that prints any log messages with level >= Debug to stderr
julia> debuglogger = ConsoleLogger(stderr, Logging.Debug)

# Enable debuglogger for a task
julia> with_logger(debuglogger) do
           @debug "a context specific log message"
       end

# Set the global logger
julia> global_logger(debuglogger)

参考

Logging 模块

创建事件

@debug message  [key=value | value ...]
@info  message  [key=value | value ...]
@warn  message  [key=value | value ...]
@error message  [key=value | value ...]

@logmsg level message [key=value | value ...]

@debug "Verbose debugging information.  Invisible by default"
@info  "An informational message"
@warn  "Something was odd.  You should pay attention"
@error "A non fatal error occurred"

x = 10
@info "Some variables attached to the message" x a=42.0

@debug begin
    sA = sum(A)
    "sum(A) = $sA is an expensive operation, evaluated only when `shouldlog` returns true"
end

for i=1:10000
    @info "With the default backend, you will only see (i = $i) ten times"  maxlog=10
    @debug "Algorithm1" i progress=i/10000
end

LogLevel(level)

julia> Logging.LogLevel(0) == Logging.Info
true

Debug

Info

Warn

Error

使用 AbstractLogger 处理事件

事件处理由覆盖与 AbstractLogger 关联的函数控制。

handle_message(logger, level, message, _module, group, id, file, line; key1=val1, ...)

shouldlog(logger, level, _module, group, id)

min_enabled_level(logger)

catch_exceptions(logger)

disable_logging(level)

Logging.disable_logging(Logging.Info) # Disable debug and info

使用日志记录器

日志记录器安装和检查

global_logger()

global_logger(logger)

with_logger(function, logger)

function test(x)
    @info "x = $x"
end

with_logger(logger) do
    test(1)
    test([1,2])
end

current_logger()

系统提供的日志记录器

NullLogger()

ConsoleLogger([stream,] min_level=Info; meta_formatter=default_metafmt,
              show_limited=true, right_justify=0)

SimpleLogger([stream,] min_level=Info)