Macros API

This page documents the macro-first logging APIs exported by ComponentLogging.

Macros work differently from functions. Macros do not take a logger as an argument; instead, you need to bind a key-value pair of current module => logger to the internal module registry of ComponentLogging. Subsequent macro calls do not require passing the logger; the logger for the current module is retrieved via a dictionary lookup.

You can use set_module_logger or @bind_logger in the __init__ function to bind the logger to the current module.

function __init__()
    set_module_logger(@__MODULE__, logger)
end
# or
function __init__()
    @bind_logger sink=logger
end

Info

Macros automatically capture the caller's module, file, and line number.

ComponentLogging.set_module_logger — Function

set_module_logger(mod::Module, logger::AbstractLogger) -> String

Bind logger to the module mod. Returns a short human-readable string summary "<Module> <- <LoggerType>".

source

ComponentLogging.get_logger — Function

get_logger(mod::Module) -> AbstractLogger

Return the logger bound to module mod, walking up parent modules if necessary. Throws an error if none is found at the root.

source

ComponentLogging.@bind_logger — Macro

@bind_logger [sink=...] [rules=...] [mod=...]

Bind a ComponentLogger to the given mod (default: caller's module). Arguments must be passed as keywords. rules may be any AbstractDict mapping groups (Symbol or NTuple{N,Symbol}) to levels (LogLevel or Integer).

Returns the constructed ComponentLogger.

Example:

@bind_logger sink=ConsoleLogger() rules=Dict(:__default__=>Info, :core=>Warn)

source

ComponentLogging.@clog — Macro

@clog [group] level msg...

Macro version of clog that captures the caller's Module, file, and line for accurate provenance. group must be a literal Symbol or tuple of literal symbols.

Example:

@clog 0 "hello"             # default group
@clog :core 1000 "hello"    # single group (literal)
@clog (:a,:b) 2000 "hello"  # specified group (literal)

source

ComponentLogging.@cdebug — Macro

@cdebug args...

Shorthand for @clog Debug args.... Emits a message at Debug level. See @clog for argument rules and caller metadata capture.

source

ComponentLogging.@cinfo — Macro

@cinfo args...

Shorthand for @clog Info args.... Emits a message at Info level. See @clog for argument rules and caller metadata capture.

source

ComponentLogging.@cwarn — Macro

@cwarn args...

Shorthand for @clog Warn args.... Emits a message at Warn level. See @clog for argument rules and caller metadata capture.

source

ComponentLogging.@cerror — Macro

@cerror args...

Shorthand for @clog Error args.... Emits a message at Error level. See @clog for argument rules and caller metadata capture.

source

ComponentLogging.@clogenabled — Macro

@clogenabled group level

Macro that expands to a boolean expression answering whether logging is enabled for the literal group and level at the call site (using the logger bound to the caller's module). group must be a literal Symbol or tuple of literal symbols.

source

ComponentLogging.@clogf — Macro

@clogf [group] level expr

Macro version of clogf. The last argument can be either a message expression or a zero-argument function (e.g. () -> begin ...; "message" end). The body is only evaluated if logging is enabled. Caller module and source location are captured automatically.

source