Logging.jl

@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 ...]

Create a log record with an informational message. For convenience, four logging macros @debug, @info, @warn and @error are defined which log at the standard severity levels Debug, Info, Warn and Error. @logmsg allows level to be set programmatically to any LogLevel or custom log level types.

message should be an expression which evaluates to a string which is a human readable description of the log event. By convention, this string will be formatted as markdown when presented.

The optional list of key=value pairs supports arbitrary user defined metadata which will be passed through to the logging backend as part of the log record. If only a value expression is supplied, a key representing the expression will be generated using Symbol. For example, x becomes x=x, and foo(10) becomes Symbol("foo(10)")=foo(10). For splatting a list of key value pairs, use the normal splatting syntax, @info "blah" kws....

There are some keys which allow automatically generated log data to be overridden:

• _module=mod can be used to specify a different originating module from the source location of the message.
• _group=symbol can be used to override the message group (this is normally derived from the base name of the source file).
• _id=symbol can be used to override the automatically generated unique message identifier. This is useful if you need to very closely associate messages generated on different source lines.
• _file=string and _line=integer can be used to override the apparent source location of a log message.

There's also some key value pairs which have conventional meaning:

• maxlog=integer should be used as a hint to the backend that the message should be displayed no more than maxlog times.
• exception=ex should be used to transport an exception with a log message, often used with @error. An associated backtrace bt may be attached using the tuple exception=(ex,bt).

Examples

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

Severity/verbosity of a log record.

The log level provides a key against which potential log records may be filtered, before any other work is done to construct the log record data structure itself.

Examples

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

Debug

Alias for LogLevel(-1000).

Info

Alias for LogLevel(0).

Warn

Alias for LogLevel(1000).

Error

Alias for LogLevel(2000).

global_logger()

Return the global logger, used to receive messages when no specific logger exists for the current task.

global_logger(logger)

Set the global logger to logger, and return the previous global logger.

current_logger()

Return the logger for the current task, or the global logger if none is attached to the task.

with_logger(function, logger)

Execute function, directing all log messages to logger.

Example

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

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

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

Logger with formatting optimized for readability in a text console, for example interactive work with the Julia REPL.

Log levels less than min_level are filtered out.

Message formatting can be controlled by setting keyword arguments:

• meta_formatter is a function which takes the log event metadata (level, _module, group, id, file, line) and returns a color (as would be passed to printstyled), prefix and suffix for the log message. The default is to prefix with the log level and a suffix containing the module, file and line location.
• show_limited limits the printing of large data structures to something which can fit on the screen by setting the :limit IOContext key during formatting.
• right_justify is the integer column which log metadata is right justified at. The default is zero (metadata goes on its own line).

SimpleLogger([stream,] min_level=Info)

Simplistic logger for logging all messages with level greater than or equal to min_level to stream. If stream is closed then messages with log level greater or equal to Warn will be logged to stderr and below to stdout.

NullLogger()

Logger which disables all messages and produces no output - the logger equivalent of /dev/null.

A logger controls how log records are filtered and dispatched. When a log record is generated, the logger is the first piece of user configurable code which gets to inspect the record and decide what to do with it.

min_enabled_level(logger)

Return the minimum enabled level for logger for early filtering. That is, the log level below or equal to which all messages are filtered.

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

Return true when logger accepts a message at level, generated for _module, group and with unique log identifier id.

catch_exceptions(logger)

Return true if the logger should catch exceptions which happen during log record construction. By default, messages are caught

By default all exceptions are caught to prevent log message generation from crashing the program. This lets users confidently toggle little-used functionality - such as debug logging - in a production system.

If you want to use logging as an audit trail you should disable this for your logger type.

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

Log a message to logger at level. The logical location at which the message was generated is given by module _module and group; the source location by file and line. id is an arbitrary unique value (typically a Symbol) to be used as a key to identify the log statement when filtering.