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

Returns

• Logger: 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::AbstractString) -> Logger

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

Arguments

• name::AbstractString: 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.

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)

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

setlevel!(logger::Logger, level::AbstractString)

Changes what level this logger should log at.

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

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

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

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

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 :is_colorized and :colors Ex) Dict{Symbol, Any}( :is_colorized => true, :opts[:colors] => Dict{AbstractString, Symbol}( "debug" => :blue, "info" => :green, ... ) )

DefaultHandler{F}(filename::AbstractString, fmt::F, opts::Dict{Symbol, Any}) 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{F, O}(io::O, fmt::F, opts::Dict{Symbol, Any}) 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 getindex or iterating will evaluate and cache the properties accessed.

Subtypes of AttributeRecord should implement Memento.getattribute(::MyRecord, ::Symbol) instead of getindex.

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{DateTime}: 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::AbstractString)

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.

• msg::AbstractString: 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 getindex (ie: record[:msg]).

Subtypes of Record should implement getindex(::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.

• file::AbstractString: 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_warn(logger, msg, expr)

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

@test_throws(logger, extype, expr)

Disables the logger and calls @test_throws extype, expr.