LoggingExtras.jl

LoggingExtras uses a compositional model where complex logging systems are built by combining simple, pure components. These components are categorized into four types:

• Sinks: The endpoints of a log message (e.g., writing to a file or console). They only decide what to do with a message, not whether to accept it.
• Filters: Wrappers that decide whether to pass a message to the underlying logger. They can be Early Filters (deciding before the message is computed) or Active Filters (deciding after the message is fully formed).
• Transformers: Wrappers that modify log message content (like severity level or message text) before passing it on. They cannot block a message.
• Tee: A hub (specifically TeeLogger) that receives one message and sends copies to multiple child loggers, allowing for complex routing.

By composing these, you can create sophisticated routing (e.g., sending errors to a file while sending everything to the console).

# Conceptual example of a composed logger
ConsoleLogger(stream, min_level) =
    MinLevelLogger(
        ActiveFilteredLogger(max_log_filter,
            PureSinkConsoleLogger(stream)
        ),
        min_level
    )

Use DatetimeRotatingFileLogger to automatically rotate log files based on a DateFormat. The logger will close the current file and open a new one whenever the filename (determined by the date/time pattern) changes.

Key Features:

• Filename Escaping: If your filename contains static parts (e.g., .log), you must escape them using raw"..." to prevent the DateFormat engine from interpreting them.
• Rotation Callback: You can pass a rotation_callback::Function as a keyword argument to perform post-processing on a file immediately after it is rotated.
• Custom Formatting: You can pass a formatter function as the first argument to control the output content.

using LoggingExtras

# Rotate logs based on minute-level precision
# Note the use of raw"" to escape the .log extension
rotating_logger = DatetimeRotatingFileLogger(pwd(), raw"\a\c\c\e\s\s-YYYY-mm-dd-HH-MM.\l\o\g")

with_logger(rotating_logger) do
    @info("This goes in one file")
    sleep(61) # Wait for the next minute to trigger rotation
    @info("This goes in another file")
end

The FormatLogger allows you to define exactly how log messages are structured by providing a formatting function: f(io::IO, log_args::NamedTuple).

Arguments:

• f: A function that takes an IO object and a NamedTuple containing log metadata (e.g., args.level, args.message, args._module).
• io or filepath: The second argument can be a writable IO object or a string representing a file path.
• append::Bool: Determines if the file is opened in append mode ("a") or truncate mode ("w").

using LoggingExtras

# Format logs to stdout with a custom pattern
logger = FormatLogger() do io, args
    println(io, args._module, " | ", "[", args.level, "] ", args.message)
end

# Format logs to a file in append mode
logger = FormatLogger("out.log"; append=true) do io, args
    println(io, args._module, " | ", "[", args.level, "] ", args.message)
end

with_logger(logger) do
    @info "This is an informational message."
end

The EarlyFilteredLogger runs earlier in the pipeline than ActiveFilteredLogger. It runs before the log message is computed, which is critical for performance if the message construction (e.g., calculating statistics) is expensive.

Because it runs early, the filter function only has access to the level, _module, id, and group fields. It cannot see the actual message content.

Example: Throttling repeated messages

using Dates, LoggingExtras

function make_throttled_logger(period)
    history = Dict{Symbol, DateTime}()
    EarlyFilteredLogger(global_logger()) do log
        if !haskey(history, log.id) || (period < now() - history[log.id])
            history[log.id] = now()
            return true
        else
            return false
        end
    end
end

throttled_logger = make_throttled_logger(Second(3))

with_logger(throttled_logger) do
    for ii in 1:10
        sleep(1)
        @info "It happened" ii
    end
end

The ActiveFilteredLogger wraps a logger and uses a filter function to decide whether to pass a message. The filter function is called with the full set of parameters of the log message (the complete log object), allowing you to filter based on the actual message content.

Example: Filter messages starting with a specific string

function yodawg_filter(log_args)
    startswith(log_args.message, "Yo Dawg!")
end

filtered_logger = ActiveFilteredLogger(yodawg_filter, global_logger())

with_logger(filtered_logger) do
    @info "Boring message"      # Ignored
    @warn "Yo Dawg! it is bad" # Logged
end

function yodawg_filter(log_args)
    startswith(log_args.message, "Yo Dawg!")
end

filtered_logger = ActiveFilteredLogger(yodawg_filter, global_logger())

with_logger(filtered_logger) do
    @info "Boring message"
    @warn "Yo Dawg! it is bad"
    @info "Another boring message"
    @info "Yo Dawg! it is all good"
end