Logging

Модуль 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.

Log event structure

Каждое событие генерирует несколько данных, некоторые из которых предоставлены пользователем, а некоторые автоматически извлечены. Давайте сначала рассмотрим данные, определенные пользователем:

Уровень логирования — это широкая категория для сообщения, которая используется для ранней фильтрации. Существует несколько стандартных уровней типа 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).

Система также генерирует некоторую стандартную информацию для каждого события:

модуль, в котором была развернута макрос для логирования.
file и line, где происходит макрос логирования в исходном коде.
Сообщение id, которое является уникальным, фиксированным идентификатором для оператора исходного кода, в котором появляется макрос ведения журнала. Этот идентификатор разработан так, чтобы быть довольно стабильным, даже если исходный код файла изменяется, при условии, что сам оператор ведения журнала остается прежним.
Группа group для события, которая по умолчанию устанавливается в базовое имя файла без расширения. Это можно использовать для более тонкой группировки сообщений по категориям, чем уровень журнала (например, все предупреждения об устаревании имеют группу :depwarn), или для логической группировки по модулям или внутри них.

Обратите внимание, что такая полезная информация, как время события, по умолчанию не включена. Это связано с тем, что такая информация может быть дорогостоящей для извлечения и также динамически доступна текущему логгеру. Просто определить custom logger, чтобы дополнить данные события временем, трассировкой, значениями глобальных переменных и другой полезной информацией по мере необходимости.

Processing log events

Как вы можете видеть в примерах, операторы журналирования не упоминают, куда идут события журнала или как они обрабатываются. Это ключевая особенность дизайна, которая делает систему составной и естественной для параллельного использования. Это достигается за счет разделения двух различных аспектов:

Создание лог-событий является задачей автора модуля, который должен решить, где будут вызываться события и какую информацию включить.
Обработка логов событий — то есть отображение, фильтрация, агрегация и запись — это задача автора приложения, который должен объединить несколько модулей в совместно работающем приложении.

Loggers

Обработка событий выполняется логгером, который является первым элементом настраиваемого пользователем кода, который видит событие. Все логгеры должны быть подтипами AbstractLogger.

Когда событие вызывается, соответствующий логгер находится путем поиска локального логгера задачи с глобальным логгером в качестве резервного варианта. Идея заключается в том, что код приложения знает, как должны обрабатываться события логирования, и находится где-то в верхней части стека вызовов. Поэтому мы должны подниматься по стеку вызовов, чтобы обнаружить логгер — то есть логгер должен быть динамически определяемым. (Это контрастирует с фреймворками логирования, где логгер лексически определяемый; предоставляется явно автором модуля или в качестве простой глобальной переменной. В такой системе неудобно контролировать логирование, комбинируя функциональность из нескольких модулей.)

Глобальный логгер может быть установлен с помощью global_logger, а локальные логгеры задач контролируются с помощью with_logger. Новые задачи наследуют логгер родительской задачи.

Библиотека предоставляет три типа логгеров. ConsoleLogger — это логгер по умолчанию, который вы видите при запуске REPL. Он отображает события в читаемом текстовом формате и пытается предоставить простой, но удобный для пользователя контроль над форматированием и фильтрацией. NullLogger — это удобный способ отбрасывать все сообщения, когда это необходимо; это эквивалент логирования потока devnull. SimpleLogger — это очень простой логгер текстового форматирования, в основном полезный для отладки самой системы логирования.

Пользовательские логгеры должны иметь перегрузки для функций, описанных в reference section.

Early filtering and message handling

Когда происходит событие, выполняется несколько шагов ранней фильтрации, чтобы избежать генерации сообщений, которые будут отклонены:

Уровень журнала сообщений проверяется на соответствие глобальному минимальному уровню (установленному через disable_logging). Это грубая, но чрезвычайно дешевая глобальная настройка.
Текущее состояние логгера проверяется, и уровень сообщения сравнивается с минимальным кэшированным уровнем логгера, который определяется вызовом Logging.min_enabled_level. Это поведение можно переопределить с помощью переменных окружения (подробности об этом позже).
Функция Logging.shouldlog вызывается с текущим логгером, принимая некоторую минимальную информацию (уровень, модуль, группа, id), которая может быть вычислена статически. Наиболее полезно, что shouldlog передается событие id, которое можно использовать для раннего отсева событий на основе кэшированного предиката.

Если все эти проверки пройдены, сообщение и пары ключ–значение полностью оцениваются и передаются текущему логгеру через функцию Logging.handle_message. handle_message() может выполнять дополнительную фильтрацию по мере необходимости и отображать событие на экране, сохранять его в файл и т.д.

Исключения, которые возникают при генерации события журнала, по умолчанию захватываются и записываются в журнал. Это предотвращает сбой приложения из-за отдельных поврежденных событий, что полезно при включении редко используемых отладочных событий в производственной системе. Это поведение можно настроить для каждого типа логгера, расширив Logging.catch_exceptions.

Testing log events

События журналирования являются побочным эффектом выполнения обычного кода, но вы можете захотеть протестировать определенные информационные сообщения и предупреждения. Модуль Test предоставляет макрос @test_logs, который можно использовать для сопоставления с образцом в потоке событий журналирования.

Environment variables

Фильтрация сообщений может быть изменена с помощью переменной окружения JULIA_DEBUG, и это простой способ включить отладочный логгинг для файла или модуля. Загрузка julia с JULIA_DEBUG=loading активирует сообщения логов @debug в loading.jl. Например, в оболочках Linux:

$ JULIA_DEBUG=loading julia -e 'using OhMyREPL'
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji due to it containing an incompatible 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 incompatible 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.

Examples

Example: Writing log events to a file

Иногда может быть полезно записывать события журнала в файл. Вот пример того, как использовать локальный для задачи и глобальный журнал для записи информации в текстовый файл:

# 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)

Example: Enable debug-level messages

Вот пример создания 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)

Reference

Logging module

Logging.Logging — Module

Утилиты для захвата, фильтрации и представления потоков событий журналов. Обычно вам не нужно импортировать Logging для создания событий журналов; для этого стандартные макросы журналирования, такие как @info, уже экспортированы Base и доступны по умолчанию.

Methods to implement		Brief description
`Logging.handle_message`		Handle a log event
`Logging.shouldlog`		Early filtering of events
`Logging.min_enabled_level`		Lower bound for log level of accepted events
Optional methods	Default definition	Brief description
`Logging.catch_exceptions`	`true`	Catch exceptions during event evaluation