Public

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.

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.

log(::Function, ::Logger, ::AbstractString)

Same as log(logger, level, msg), but in this case the message can be a function that returns the log message string.

Arguments

• msg::Function: a function that returns a message String

• logger::Logger: the logger to log to.

• level::AbstractString: the log level as a String

Throws

• CompositeException: may be thrown if an error occurs in one of the handlers (which are run with @async)

log(logger::Logger, level::AbstractString, msg::AbstractString)

Creates a Dict with the logger name, level, levelnum and message and calls the other log method (which may recursively call itself on parent loggers with the created Dict).

Arguments

• logger::Logger: the logger to log to.

• level::AbstractString: the log level as a String

• msg::AbstractString: the msg to log as a String

Throws

• CompositeException: may be thrown if an error occurs in one of the handlers (which are run with @async)

log(logger::Logger, args::Dict{Symbol, Any})

Logs logger.record(args) to its handlers if it has the appropriate args[:level] and args[:level] is above the priority of logger.level. If this logger is not the root logger and logger.propagate is true then the parent logger is called.

NOTE: This method calls all handlers asynchronously and is recursive, so you should call this method with a @sync in order to synchronize all handler tasks.

Arguments

• logger::Logger: the logger to log args to.

• args::Dict: a dict of msg fields and values that should be passed to logger.record.

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.

add_handler(logger::Logger, handler::Handler, name)

Adds a new handler to logger.handlers. If a name is not provided a random one will be generated.

Arguments

• logger::Logger: the logger to use.

• handler::Handler: the handler to add.

• name::AbstractString: a name to identify the handler.

add_level(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.

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.

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.

get_handlers(logger::Logger)

Returns logger.handlers

get_logger(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.

get_logger(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.

is_root(::Logger)

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

is_set(: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.

remove_handler(logger::Logger, name)

Removes the Handler with the provided name from the logger.handlers.

set_level(logger::Logger, level::AbstractString)

Changes what level this logger should log at.

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

DefaultHandler{F<Formatter, O<:IO}(io::O, fmt::F, opts::Dict{Symbol, Any})

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}())

DefaultHandler{F<Formatter}(filename::AbstractString, fmt::F, opts::Dict{Symbol, Any})`

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}())

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

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.

log(handler::Handler, rec::Record)

Checks the Handler filters and if they all pass then emit the record.

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

Handles printing any Record with any Formatter and IO types.

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

Handles printing any records with any Formatter and a Syslog IO type.

set_level(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. ...

Formatter

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

JsonFormatter

Uses the JSON pkg to format the Record into a valid JSON string.

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

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

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

Converts :date, :lookup and :stacktrace to strings and dicts respectively and call JSON.json() on the resulting dictionary.

DefaultRecord

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{Symbol}: 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, 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

Are an Attribute container used to store information about a log events including the msg, date, level, stacktrace, etc. Formatters use Records to format log message strings.

NOTE: you should access Attributes in a Record by using getindex (ie: record[:msg]) as this will correctly extract the value from the Attribute container.

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.

Syslog <: IO

Syslog handle writing message to syslog by shelling out to the logger command.

Fields

• facility::Symbol: The syslog facility to write to (e.g., :local0, :ft, :daemon, etc) (defaults to :local0)

• tag::AbstractString: a tag to use for all message (defaults to "julia")

• pid::Integer: tags julia's pid to messages (defaults to -1 which doesn't include the pid)