SeqLoggers

SeqLogger(
    server_url::AbstractString;
    min_level::Logging.LogLevel=Logging.Info,
    api_key::AbstractString="",
    batch_size::Int=10,
    event_properties...
)

Logger to post log events to a Seq log server.

Inputs

• server_url – Seq server url (e.g. "http://localhost:5341")
• min_level – (optional, default=Logging.Info) minimal log level to filter the log events
• api_key – (optional, default="") API-key string for registered Applications
• batch_size – (optional, default=10) number of log events sent to Seq server in single post
• event_properties – (optional) global log event properties

Global Log Event Properties

The SeqLogger constructor allows to add global log event properties to the logger using keyword-arguments.

SeqLogger("http://localhost:5341"; App="DJSON", Env="PROD", Id="24e0d145-d385-424b-b6ec-081aa17d504a")

Local Log Event Properties

For each individual log event, additional log event properties can be added which only apply to a single log event.

@info "Log additional user id {userId}" userId="1"

Note: This only works, if the Logging.current_logger is of type SeqLogger or "contains" a SeqLogger.

Logging.handle_message(logger::SeqLogger, args...; kwargs...)

Extends the function Logging.handle_message for SeqLoggers.

Note

• If the event batch of the logger is "full", the log events are flushed.
• A ReentrantLock is used to make the logger thread-safe.

Logging.with_logger(@nospecialize(f::Function), demuxLogger::TeeLogger)

Extends the method Logging.with_logger to work for a LoggingExtras.TeeLogger containing a SeqLogger.

Note

This constitutes as type piracy and should be treated with caution. But it is necessary such that also TeeLoggers that contain a SeqLogger do flush the log events after exiting the with_logger function.

Logging.with_logger(@nospecialize(f::Function), logger::SeqLogger)

Extends the function Logging.with_logger for SeqLoggers.

Note

After running the function f, the SeqLogger needs to flush the log events to make sure that the entire log batch is sent to the Seq server.

AdvancedFileLogger(
    dir::AbstractString, 
    file_name_pattern::AbstractString;
    log_format_function::Function=print_standard_format,
    min_level=Logging.Info
)

Return an file logger with extra functionality (in contrast to a FileLogger which is only a interface to SimpleLogger).

Parameters

• dir – log file directory
• file_name_pattern – file name pattern for rotating log files (e.g. raw"\a\c\c\e\s\s-YYYY-mm-dd-HH-MM.\l\o\g"))
• log_format_function – optional, default=print_standard_format
• min_level – optional, default=Logging.Info

Features

• Define a DateFormat/String file pattern for rotating log messages to a new file → argument file_name_pattern
• Provide a custom formatting function for writting to log files → argument log_format_function

Returns

A MinLevelLogger which includes a DatetimeRotatingFileLogger.

add_timestamp(logger::AbstractLogger)

Logger transformation function that prepends a timestamp to a logging message.

event_property!(teelogger::LoggingExtras.TeeLogger; kwargs...)

Extend event_property! to a work for a LoggingExtras.TeeLogger containing a SeqLogger.

event_property!(logger::SeqLogger; kwargs...)

Add one or more event properties to the list of global event properties in logger.

Example

event_property!(logger, user="Me", userId=1)

Note

If a new event property with identical name as an existing on is added with event_property!, the existing property in new_event_properties is not replaced, the new property is just added to new_event_properties. However, this still works since on the Seq side the raw post events considers the last property key as the final one if more than one has the same key.

flush_current_logger()

Post the events in the logger batch event for the logger for the current task, or the global logger if none is attached to the task.

Note

In the main moduel of Atom, the current_logger is Atom.Progress.JunoProgressLogger(). Therefore, if you set SeqLogger as a Logging.global_logger in in Atom use flush_global_logger.

flush_events(teeLogger::LoggingExtras.TeeLogger)

Extend flush_events to a work for a LoggingExtras.TeeLogger containing a SeqLogger.

flush_events(logger::SeqLogger)

Post all log events contained in the event batch of logger to the Seq server and clear the event batch afterwards.

flush_global_logger()

Post the events in the logger batch event for the global logger.

Note

If the logger is run with Logging.with_logger, this is considered a current logger Logging.current_logger and flush_current_logger. needs to be used.

get_log_level(key::String)::Logging.LogLevel

Return the Loggin.LogLevel corresponding to the input string.

get_logger(logger_type::AbstractString, logger_config::AbstractDict)::AbstractLogger

Create logger struct from logger type name and Dict with required parameters.

By default, the following logger types are supported:

• "SeqLogger" → SeqLogger
• "ConsoleLogger" → ConsoleLogger
• "FileLogger" → FileLogger

Use register_logger! to add custom AbstractLoggers.

get_transformation_function(key::String)

Convert a string (from config) into a transformation function.

By default, the following transformation functions are supported:

• "identity" → identity: no transformation
• "add_timestamp" → add_timestamp: add timestamp at the beginning of log message

Use register_transformation_function! to add custom transformation functions.

joinurl(left::AbstractString, right::AbstractString)

Join the left and right part of a URL, by removing trailing frontslashes and add an additional frontslashes if required.

load_advanced_filelogger(logger_config::AbstractDict)::AbstractLogger

Return a DatetimeRotatingFileLogger or TransformerLogger according to logger_config.

Config Parameters

• "dir_path" – required
• "min_level" – required ("DEBUG", "INFO", "WARN", "ERROR")
• "file_name_pattern" – required e.g. "\a\c\c\e\s\s-YYYY-mm-dd-HH-MM.\l\o\g"
• "transformation" – optional, default identity

Example

logging_config = Dict(
    "dir_path" => "C:/Temp",
    "min_level" => "ERROR",
    "file_name_pattern" => "\a\c\c\e\s\s-YYYY-mm-dd-HH-MM.\l\o\g",
    "transformation" => "add_timestamp",
)
seq_logger = SeqLoggers.load_advanced_filelogger(log_dict)

load_consolelogger(logger_config::AbstractDict)::Union{ConsoleLogger, TransformerLogger}

Return a ConsoleLogger or TransformerLogger according to logger_config.

Config Parameters

• "min_level" – required ("DEBUG", "INFO", "WARN", "ERROR")
• "transformation" – optional, default identity

Example

logging_config = Dict(
    "min_level" => "ERROR",
    "transformation" => "add_timestamp",
)

seq_logger = SeqLoggers.load_consolelogger(log_dict)

load_consolelogger(logger_config::AbstractDict)::AbstractLogger

Return a MinLevelLogger{FileLogger} or TransformerLogger according to logger_config.

Config Parameters

• "file_path" – required
• "min_level" – required ("DEBUG", "INFO", "WARN", "ERROR")
• "append" – optional, default true, append to file if true, otherwise truncate file. (See LoggingExtras.FileLogger for more information.)
• "transformation" – optional, default identity

Example

logging_config = Dict(
    "file_path" => "C:/Temp/test.log",
    "min_level" => "ERROR",
    "append" => true,
    "transformation" => "add_timestamp",
)
seq_logger = SeqLoggers.load_filelogger(log_dict)

load_logger_from_config(config::Dict)::TeeLogger

Create a TeeLoger, a collection of logger, from a configuration Dict.

Note

• A TeeLogger struct allows to send the same log message to all loggers included in the TeeLoger at once.
• The configuration Dict requires as "logging" field, see example for more details.

Example

config = Dict(
    ...,
    "logging" => [
        # logger_type => logger_config_dict,
        "SeqLogger" => Dict(...),
        ...
    ],
    ...
)

Returns

TeeLogger as defined in config

load_logger_from_config(file_path::AbstractString)::TeeLogger

Create a combined logger from a config file path.

Note

A combined logger is a TeeLogger struct that allows to send the same log message to all loggers included in the combined logger at once.

load_seqlogger(logger_config::AbstractDict)::Union{SeqLogger, TransformerLogger}

Return a SeqLogger or TransformerLogger according to logger_config.

Config Parameters

• "server_url" – required
• "min_level" – required ("DEBUG", "INFO", "WARN", "ERROR")
• "transformation" – optional, default identity
• "api_key" – optional, default ""
• "batch_size" – optional, default 10

All other config parameters are used as global event properties.

Example

log_dict = Dict(
    "server_url" => "http://subdn215:5341/",
    "min_level" => "INFO",
    "batch_size" => 12,
    "App" => "SeqLoggers_Test",
    "Env" => "Test"
)
seq_logger = SeqLoggers.load_seqlogger(log_dict)

parse_event_str_from_args(logger::SeqLogger, message_args::NamedTuple)::String

Create a log event string from the named tuple message_args.

post_request(logger::SeqLogger, json_str::AbstractString)

Send POST request with body json_str to Seq server.

print_standard_format(io::IO, log_args::NamedTuple)

Print log message and keyword arguments in a format similar to the one used by the ConsoleLogger.

register_logger!(logger_type::AbstractString, logger_constructor::Function)

Register a new logger type.

Registering enables the user to use custom AbstractLogger struct, defined outside of SeqLoggers, to be used with load_logger_from_config.

register_transformation_function!(key::AbstractString, transformation_function::Function)

Register new transformation function.

Registering enables the user to use custom transformation functions, defined outside of SeqLoggers, to be used with load_logger_from_config.

run_with_logger(f::Function, logger::AbstractLogger, args...)

Helper function that applies advanced event logging to the execution of f(args...).

In addition to normal log events (@info, ...), the logger catches exceptions to create error log events. Afterwards, the exception will continue propagation as if it had not been caught.

Inputs

• f – function to execute
• args – function arguments

Retunrs

Result from applying f(args...) including thrown exceptions.

Notes

The function run_with_logger applies a new logger to the function call f(args...). All loggers applied on a "higher level" are replaced for the lifespan of the function call.

Example

logger = ConsoleLogger(stderr, Logging.Info)
run_with_logger(logger, -3) do number
    @info "Compute square root for negative number: $number"
    sqrt(number)
end

stringify(; kwargs...)

Convert keywords arguments into a string that conforms the log event message structure used in the Seq logger.

to_seq_level(log_level::Base.CoreLogging.LogLevel)

Given a Logging.LogLevel return the string identifier for the log level used on the Seq server.