Macros API

The macro API provides module-bound convenience. Unlike the explicit function API, logging macros do not take a logger argument at each call site. Instead, they resolve the logger associated with the calling module through ComponentLogging's module registry.

Module registry

A logger can be bound directly:

set_module_logger(@__MODULE__, logger)

or with @bind_logger:

@bind_logger sink=logger

For packages, binding is commonly performed from __init__:

function __init__()
    set_module_logger(@__MODULE__, logger)
end

If the calling module has no direct binding, get_logger walks through parent modules until it finds one. This allows a package-level binding to serve submodules by default while still permitting a submodule to install its own logger when needed.

MyPackage.Submodule
        │
        ├─ direct binding? ── yes → use it
        │
        └─ no
           ↓
      MyPackage binding

Module bindings are safe to update concurrently. Since v0.3.0 the registry uses the same copy-on-write snapshot model as ComponentLogger, so lookups remain lock-free on the normal read path.

Logging macros

The main macro interface mirrors familiar logging operations while adding explicit component groups:

@clog :solver 0 "starting"
@cdebug :solver "debug message"
@cinfo :solver "information"
@cwarn :solver "warning"
@cerror :solver "error"

Hierarchical tuple groups are also supported where accepted by the macro:

@clog (:solver, :iteration) 0 "iteration started"

@clogenabled and @clogf provide the macro equivalents of the corresponding function APIs.

Caller metadata

Macros automatically capture the caller's module, file, and line number. This is the main ergonomic advantage over the explicit function API when source-location metadata matters.

Performance trade-off

The macro path performs a module-registry lookup before reaching the logger. This is intentionally a convenience path rather than the minimum-overhead path.

For extremely hot code, or when a logger already exists as an explicit argument, prefer clog, clogenabled, and clogf directly. See Function API.

Reference

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