Logging

    The system provides several advantages over peppering your source code with calls to . First, it allows you to control the visibility and presentation of messages without editing the source code. For example, in contrast to the @warn above

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

    will produce no output by default. Furthermore, it’s very cheap to leave debug statements like this in the source code because the system avoids evaluating the message if it would later be ignored. In this case sum(rand(100)) and the associated string processing will never be executed unless debug logging is enabled.

    Second, the logging tools allow you to attach arbitrary data to each event as a set of key–value pairs. This allows you to capture local variables and other program state for later analysis. For example, to attach the local array variable A and the sum of a vector v as the key s you can use

    1. A = ones(Int, 4, 4)
    2. v = ones(100)
    3. @info "Some variables"  A  s=sum(v)
    5. # output
    6. ┌ Info: Some variables
    7. │   A =
    8. │    4×4 Matrix{Int64}:
    9. │     1  1  1  1
    10. │     1  1  1  1
    11. │     1  1  1  1
    12. │     1  1  1  1
    13. └   s = 100.0

    All of the logging macros @debug, @info, @warn and @error share common features that are described in detail in the documentation for the more general macro .

    Each event generates several pieces of data, some provided by the user and some automatically extracted. Let’s examine the user-defined data first:

    • The log level is a broad category for the message that is used for early filtering. There are several standard levels of type LogLevel; user-defined levels are also possible. Each is distinct in purpose:

      • Debug is information intended for the developer of the program.

      These events are disabled by default.

      • Info is for general information to the user.

      Think of it as an alternative to using println directly.

      • Warn means something is wrong and action is likely required

      but that for now the program is still working.

      • Error means something is wrong and it is unlikely to be recovered,

      at least by this part of the code. Often this log-level is unneeded as throwing an exception can convey all the required information.

    • The message is an object describing the event. By convention AbstractStrings passed as messages are assumed to be in markdown format. Other types will be displayed using print(io, obj) or string(obj) for text-based output and possibly show(io,mime,obj) for other multimedia displays used in the installed logger.

    • Optional key–value pairs allow arbitrary data to be attached to each event. Some keys have conventional meaning that can affect the way an event is interpreted (see ).

    The system also generates some standard information for each event:

    • The module in which the logging macro was expanded.
    • The file and line where the logging macro occurs in the source code.
    • A message id that is a unique, fixed identifier for the source code statement where the logging macro appears. This identifier is designed to be fairly stable even if the source code of the file changes, as long as the logging statement itself remains the same.
    • A group for the event, which is set to the base name of the file by default, without extension. This can be used to group messages into categories more finely than the log level (for example, all deprecation warnings have group :depwarn), or into logical groupings across or within modules.

    Notice that some useful information such as the event time is not included by default. This is because such information can be expensive to extract and is also dynamically available to the current logger. It’s simple to define a custom logger to augment event data with the time, backtrace, values of global variables and other useful information as required.

    Processing log events

    As you can see in the examples, logging statements make no mention of where log events go or how they are processed. This is a key design feature that makes the system composable and natural for concurrent use. It does this by separating two different concerns:

    • Creating log events is the concern of the module author who needs to decide where events are triggered and which information to include.
    • Processing of log events — that is, display, filtering, aggregation and recording — is the concern of the application author who needs to bring multiple modules together into a cooperating application.

    Processing of events is performed by a logger, which is the first piece of user configurable code to see the event. All loggers must be subtypes of .

    When an event is triggered, the appropriate logger is found by looking for a task-local logger with the global logger as fallback. The idea here is that the application code knows how log events should be processed and exists somewhere at the top of the call stack. So we should look up through the call stack to discover the logger — that is, the logger should be dynamically scoped. (This is a point of contrast with logging frameworks where the logger is lexically scoped; provided explicitly by the module author or as a simple global variable. In such a system it’s awkward to control logging while composing functionality from multiple modules.)

    The global logger may be set with global_logger, and task-local loggers controlled using . Newly spawned tasks inherit the logger of the parent task.

    There are three logger types provided by the library. ConsoleLogger is the default logger you see when starting the REPL. It displays events in a readable text format and tries to give simple but user friendly control over formatting and filtering. is a convenient way to drop all messages where necessary; it is the logging equivalent of the devnull stream. is a very simplistic text formatting logger, mainly useful for debugging the logging system itself.

    Custom loggers should come with overloads for the functions described in the reference section.

    Early filtering and message handling

    When an event occurs, a few steps of early filtering occur to avoid generating messages that will be discarded:

    1. The message log level is checked against a global minimum level (set via ). This is a crude but extremely cheap global setting.
    2. The current logger state is looked up and the message level checked against the logger’s cached minimum level, as found by calling Logging.min_enabled_level. This behavior can be overridden via environment variables (more on this later).
    3. The function is called with the current logger, taking some minimal information (level, module, group, id) which can be computed statically. Most usefully, shouldlog is passed an event id which can be used to discard events early based on a cached predicate.

    If all these checks pass, the message and key–value pairs are evaluated in full and passed to the current logger via the Logging.handle_message function. handle_message() may perform additional filtering as required and display the event to the screen, save it to a file, etc.

    Exceptions that occur while generating the log event are captured and logged by default. This prevents individual broken events from crashing the application, which is helpful when enabling little-used debug events in a production system. This behavior can be customized per logger type by extending .

    Log events are a side effect of running normal code, but you might find yourself wanting to test particular informational messages and warnings. The Test module provides a @test_logs macro that can be used to pattern match against the log event stream.

    Environment variables

    Message filtering can be influenced through the JULIA_DEBUG environment variable, and serves as an easy way to enable debug logging for a file or module. For example, loading julia with JULIA_DEBUG=loading will activate @debug log messages in loading.jl:

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

    Similarly, the environment variable can be used to enable debug logging of modules, such as Pkg, or module roots (see ). To enable all debug logging, use the special value all.

    To turn debug logging on from the REPL, set ENV["JULIA_DEBUG"] to the name of the module of interest. Functions defined in the REPL belong to module Main; logging for them can be enabled like this:

    1. julia> foo() = @debug "foo"
    2. foo (generic function with 1 method)
    4. julia> foo()
    6. julia> ENV["JULIA_DEBUG"] = Main
    7. Main
    9. julia> foo()
    10. ┌ Debug: foo

    Sometimes it can be useful to write log events to a file. Here is an example of how to use a task-local and global logger to write information to a text file:

    1. # Load the logging module
    2. julia> using Logging
    4. # Open a textfile for writing
    5. julia> io = open("log.txt", "w+")
    6. IOStream(<file log.txt>)
    8. # Create a simple logger
    9. julia> logger = SimpleLogger(io)
    10. SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())
    12. # Log a task-specific message
    13. julia> with_logger(logger) do
    14.            @info("a context specific log message")
    15.        end
    17. # Write all buffered messages to the file
    18. julia> flush(io)
    20. # Set the global logger to logger
    21. julia> global_logger(logger)
    22. SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())
    24. # This message will now also be written to the file
    25. julia> @info("a global log message")
    27. # Close the file
    28. julia> close(io)

    Logging.Logging — Module

    Logging.@logmsg — Macro

    1. @debug message  [key=value | value ...]
    2. @info  message  [key=value | value ...]
    3. @warn  message  [key=value | value ...]
    4. @error message  [key=value | value ...]
    6. @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 . 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.
    • _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 .

    Examples

    1. @debug "Verbose debugging information.  Invisible by default"
    2. @info  "An informational message"
    3. @warn  "Something was odd.  You should pay attention"
    4. @error "A non fatal error occurred"
    6. x = 10
    7. @info "Some variables attached to the message" x a=42.0
    9. @debug begin
    10.     sA = sum(A)
    11.     "sum(A) = $sA is an expensive operation, evaluated only when `shouldlog` returns true"
    12. end
    14. for i=1:10000
    15.     @info "With the default backend, you will only see (i = $i) ten times"  maxlog=10
    16.     @debug "Algorithm1" i progress=i/10000
    17. end

    source

    — Type

    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

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

    source

    Event processing is controlled by overriding functions associated with AbstractLogger:

    — Type

    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.

    source

    — Function

    1. 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.

    Logging.shouldlog — Function

    1. 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.

    Logging.min_enabled_level — Function

    1. 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.

    Logging.catch_exceptions — Function

    1. catch_exceptions(logger)

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

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

    Logging.disable_logging — Function

    1. disable_logging(level)

    Disable all log messages at log levels equal to or less than level. This is a global setting, intended to make debug logging extremely cheap when disabled.

    Examples

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

    Logger installation and inspection:

    Logging.global_logger — Function

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

    1. global_logger(logger)

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

    Logging.with_logger — Function

    1. with_logger(function, logger)

    Execute function, directing all log messages to logger.

    Example

    1. function test(x)
    2.     @info "x = $x"
    3. end
    5. with_logger(logger) do
    6.     test(1)
    7.     test([1,2])
    8. end

    Logging.current_logger — Function

    1. current_logger()

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

    Loggers that are supplied with the system:

    Logging.NullLogger — Type

    1. NullLogger()

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

    Logging.ConsoleLogger — Type

    1. ConsoleLogger(stream=stderr, min_level=Info; meta_formatter=default_metafmt,
    2.               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).

    Logging.SimpleLogger — Type

    1. SimpleLogger(stream=stderr, min_level=Info)

    Simplistic logger for logging all messages with level greater than or equal to min_level to .