Public

config!([logger], level; fmt::AbstractString, levels::Dict{AbstractString, Int}, colorized::Bool) -> Logger

Sets the Memento._log_levels, creates a default root logger with a DefaultHandler that prints to stdout.

Arguments

• 'logger::Union{Logger, AbstractString}`: The logger to configure (optional)
• level::AbstractString: the minimum logging level to log message to the root logger (required).

Keywords

• fmt::AbstractString: a format string to pass to the DefaultFormatter which describes how to log messages (defaults to Memento.DEFAULT_FMT_STRING)
• levels: the default logging levels to use (defaults to Memento._log_levels).
• colorized: whether or not the message to stdout should be colorized.
• recursive: whether or not to recursive set the level of all child loggers.
• substitute: whether or not to substitute the global logger with Memento (only supported on julia 0.7).
• propagate: whether the logger should also send messages to parent loggers (default: true)

Returns

• Logger: the logger passed in, or the root logger.

Logger

A Logger is responsible for converting msg strings into Records which are then passed to each handler. By default loggers propagate their message to their parent loggers.

Fields

• name::AbstractString: is the name of the logger (required).
• handlers::Dict{Any, Handler}: is a collection of Handlers (defaults to empty Dict).
• level::AbstractString: the current minimum logging level for the logger to log message to handlers (defaults to "not_set").
• levels::Dict{AbstractString, Int}: a mapping of available logging levels to their relative priority (represented as integer values) (defaults to using Memento._log_levels)
• record::Type: the Record type that should be produced by this logger (defaults to DefaultRecord).
• propagate::Bool: whether or not this logger should propagate its message to its parent (defaults to true).

error(logger::Logger, msg::AbstractString)

Logs the message at the error level and throws an ErrorException with that message

error(msg::Function, logger::Logger)

Logs the message produced by the provided function at the error level and throws an ErrorException with that message.

error(logger::Logger, exc::Exception)

Calls error(logger, msg) with the contents of the Exception, then throw the Exception. If the exception is a CompositeException, each contained exception is logged, then the CompositeException is thrown.

addlevel!(logger::Logger, level::AbstractString, val::Int)

Adds a new level::String and priority::Int to the logger.levels

alert(logger::Logger, msg::AbstractString)

Logs the message at the alert level and throws an ErrorException with that message

alert(msg::Function, logger::Logger)

Logs the message produced by the provided function at the alert level and throws an ErrorException with that message.

alert(logger::Logger, exc::Exception)

Calls alert(logger, msg) with the contents of the Exception, then throw the Exception. If the exception is a CompositeException, each contained exception is logged, then the CompositeException is thrown.

critical(logger::Logger, msg::AbstractString)

Logs the message at the critical level and throws an ErrorException with that message

critical(msg::Function, logger::Logger)

Logs the message produced by the provided function at the critical level and throws an ErrorException with that message.

critical(logger::Logger, exc::Exception)

Calls critical(logger, msg) with the contents of the Exception, then throw the Exception. If the exception is a CompositeException, each contained exception is logged, then the CompositeException is thrown.

debug(logger::Logger, msg::AbstractString)

Logs the message at the debug level.

debug(msg::Function, logger::Logger)

Logs the message produced by the provided function at the debug level.

emergency(logger::Logger, msg::AbstractString)

Logs the message at the emergency level and throws an ErrorException with that message

emergency(msg::Function, logger::Logger)

Logs the message produced by the provided function at the emergency level and throws an ErrorException with that message.

emergency(logger::Logger, exc::Exception)

Calls emergency(logger, msg) with the contents of the Exception, then throw the Exception. If the exception is a CompositeException, each contained exception is logged, then the CompositeException is thrown.

getfilters(logger::Logger) -> Array{Filter}

Returns the filters for the logger.

gethandlers(logger::Logger)

Returns logger.handlers

getlevel(::Logger) -> AbstractString

Returns the current logger level.

getlogger(name="root") -> Logger

If the logger or its parents do not exist then they are initialized with no handlers and not set.

Arguments

• name: the name of the logger (defaults to "root")

Returns

• Logger: the logger.

getlogger(name::Module) -> Logger

Converts the Module to a String and calls get_logger(name::String).

Arguments

• name::Module: the Module a logger should be associated

Returns

• Logger: the logger associated with the provided Module.

Returns the logger.

info(logger::Logger, msg::AbstractString)

Logs the message at the info level.

info(msg::Function, logger::Logger)

Logs the message produced by the provided function at the info level.

ispropagating(::Logger)

Returns true or false as to whether the logger is propagating.

isroot(::Logger)

Returns true if logger.nameis "root" or ""

isset(::Logger)

Returns true or false as to whether the logger is set. (ie: logger.level != "not_set")

notice(logger::Logger, msg::AbstractString)

Logs the message at the notice level.

notice(msg::Function, logger::Logger)

Logs the message produced by the provided function at the notice level.

setlevel!(f::Function, logger::Logger, level::AbstractString; recursive=false)

Temporarily change the level a logger will log at for the duration of the function f.

setlevel!(logger::Logger, level::AbstractString; recursive=false)

Changes what level this logger should log at.

setpropagating!([::Function], ::Logger, [::Bool])

Sets the logger to be propagating or not (Defaults to true).

setrecord!(logger::Logger, rec::Type{R}) where {R<:Record}

Sets the record type for the logger.

Arguments

• logger::Logger: the logger to set.
• rec::Record: A Record type to use for logging messages (ie: DefaultRecord).

warn(logger::Logger, msg::AbstractString)

Logs the message at the warn level.

warn(msg::Function, logger::Logger)

Logs the message produced by the provided function at the warn level.

warn(logger::Logger, exc::Exception)

Takes an exception and logs it. If the exception is a CompositeException, each contained exception is logged.

DefaultHanlder

The DefaultHandler manages any Formatter, IO and Record.

Fields:

• fmt: a Formatter for converting Records to Strings
• io: an IO type for printing String to.
• opts: a dictionary of optional arguments such as :iscolorized and :colors Ex) ```Dict{Symbol, Any}( :iscolorized => true, :opts[:colors] => Dict{AbstractString, Symbol}( "debug" => :blue, "info" => :green, ... ) )```

DefaultHandler(
    filename::AbstractString,
    fmt::F=DefaultFormatter(),
    opts=Dict{Symbol, Any}();
    levels=nothing,
) where {F<:Formatter}

Creates a DefaultHandler with a IO handle to the specified filename.

Arguments

• filename::AbstractString: the filename of a log file to write to
• fmt::Formatter: the Formatter to use (default to DefaultFormatter())
• opts::Dict: the optional arguments (defaults to Dict{Symbol, Any}())

DefaultHandler(
    io::O,
    fmt::F=DefaultFormatter(),
    opts=Dict{Symbol, Any}();
    levels=nothing,
) where {F<:Formatter, O<:IO}

Creates a DefaultHandler with the specified IO type.

Arguments

• io::IO: the IO type
• fmt::Formatter: the Formatter to use (default to DefaultFormatter())
• opts::Dict: the optional arguments (defaults to Dict{Symbol, Any}())

Handler

Manage formatting Records and printing the resulting String to an IO type. All Handler subtypes must implement at least 1 log(::Handler, ::Record) method.

NOTE: Handlers can useful if you need to special case logging behaviour based on the Formatter, IO and/or Record types.

emit{F, O}(handler::DefaultHandler{F ,O}, rec::Record) where {F<:Formatter, O<:IO}

Handles printing any Record with any Formatter and IO types.

getfilters(handler::Handler) -> Array{Memento.Filter}

Returns the filters for the handler. The default is the standard level-based filter.

getlevel(::Handler) -> AbstractString

Returns the current handler level. The default is "not_set".

setlevel!(handler::DefaultHandler, level::AbstractString)

Sets the minimum level required to emit the record from the handler.

DefaultFormatter

The DefaultFormatter uses a simple format string to build the log message. Fields from the Record to be used should be wrapped curly brackets.

Ex) "[{level} | {name}]: {msg}" will print message of the form [info | root]: my info message. [warn | root]: my warning message. ...

DictFormatter([aliases, serializer])

Formats the record to Dict that is amenable to serialization formats such as JSON and then runs the serializer function on the produced dictionary.

Arguments

• aliases::Dict{Symbol, Symbol}: Mapping where the keys represent aliases and values

represent existing record attributes to include in the dictionary (defaults to all attributes).

• serializer::Function: A function that takes a Dictionary and returns a string. Defaults

to string(dict).

Formatter

A Formatter must implement a format(::Formatter, ::Record) method which takes a Record and returns a String representation of the log Record.

format(::DefaultFormatter, ::Record) -> String

Iteratively replaces entries in the format string with the appropriate fields in the Record.

format(::DictFormatter, ::Record) -> Dict

Converts :date, :lookup and :stacktrace to strings and dicts respectively.

AttributeRecord <: Record

A Record which stores its properties as Attributes for lazy evaluation.

Calling getproperty or iterating will evaluate and cache the properties accessed.

DefaultRecord <: AttributeRecord

Stores the most common logging event information. NOTE: if you'd like more logging attributes you can:

1. add them to DefaultRecord and open a pull request if the new attributes are applicable to most applications.
2. make a custom Record type.

Fields

• date::Attribute{ZonedDateTime}: timestamp of log event
• level::Attribute{AbstractString}: log level
• levelnum::Attribute{Int}: integer value for log level
• msg::Attribute{AbstractString}: the log message itself
• name::Attribute{AbstractString}: the name of the source logger
• pid::Attribute{Int}: the pid of where the log event occured
• lookup::Attribute{StackFrame}: the top StackFrame
• stacktrace::Attribute{StackTrace}: a stacktrace

DefaultRecord(name::AbstractString, level::AbstractString, levelnum::Int, msg)

Takes a few initial log record arguments and creates a DefaultRecord.

Arguments

• name::AbstractString: the name of the source logger.
• level::AbstractString: the log level.
• levelnum::Int: the log level number.
• msg: the message being logged.

Record

A dictionary-like container with Symbol keys used to store information about a log events including the msg, date, level, stacktrace, etc. Formatters use Records to format log message strings.

You can access the properties of a Record by using getproperty (ie: record.msg).

Subtypes of Record should implement getproperty(::MyRecord, ::Symbol) and key-value pair iteration.

getlevel(::Record) -> AbstractString

Returns the record level.

FileRoller <: IO

Is responsible for managing a rolling log file.

Fields

• prefix::AbstractString: filename prefix for the log.
• folder::AbstractString: directory where the log should be written.
• filepath::AbstractString: the full filepath for the log
• file::IO: the current file IO handle
• byteswritten::Int64: keeps track of how many bytes have been written to the current file.
• max_sz::Int: the maximum number of bytes written to a file before rolling over to another.

FileRoller(prefix, dir; max_size=DEFAULT_MAX_FILE_SIZE)

Creates a rolling log file in the specified directory with the given prefix.

FileRoller(prefix; max_size=DEFAULT_MAX_FILE_SIZE)

Creates a rolling log file in the current working directory with the specified prefix.

@test_log(logger, level, msg, expr)

Adds a temporary test handler to the logger that checks for a record with the level and msg before executing the expr. The handler is always removed after executing expr.

@test_nolog(logger, level, msg, expr)

Adds a temporary test handler to the logger that checks that there was no log record with the expected level and msg before executing the expr. The handler is always removed after executing expr.

@test_warn(logger, msg, expr)

Convenience macro that calls Memento.TestUtils.@test_log(logger, "warn", msg, expr).

@test_throws(logger, extype, expr)

Disables the logger and calls @test_throws extype, expr.