Function API

This page documents the function-first logging APIs exported by ComponentLogging. All functions require the logger to be passed explicitly as the first argument. In application code you will typically define forwarding helpers to avoid threading the logger manually.

When you already have a logger available (e.g. stored in a const or a Ref), calling clog(logger, ...) bypasses the task-local logger lookup performed by stdlib logging macros (@info, @logmsg, …) and can reduce overhead in hot paths.

Forwarding macro

@forward_logger generates module-local forwarding methods (clog, clogenabled, clogf, set_log_level, with_min_level) so you can call them without explicitly passing a logger at every call site.

Info

The function APIs do not automatically pass the current module, file, or line information; you need to provide them manually if needed. In the example below, the current module, file, and line are explicitly passed at the call site.

clog(logger, :core, 0, "hello"; _module=@__MODULE__, file=@__FILE__, line=@__LINE__)

ComponentLogging.clog — Function

clog(logger, group, level, msg...; _module, file, line, kwargs...)

Emit a log message through the given or implicit logger. group is a Symbol or NTuple{N,Symbol}. level may be LogLevel or Integer. msg can be one or more values; tuples are passed through as-is.

Keyword arguments file, line, and arbitrary kwargs... are forwarded to the underlying logger sink.

If @forward_logger is already used, the following forwarding signatures are available:

clog(group, level, msg...; kwargs...)
clog(group, msg...; kwargs...)

source

ComponentLogging.clogenabled — Function

clogenabled(logger, group, level) -> Bool
clogenabled(logger, group) -> Bool

Return whether logging is enabled for the given logger, group, and level. If level is omitted, Info is used.

If @forward_logger is already used, the following forwarding signatures are available:

clogenabled(group, level) -> Bool
clogenabled(group) -> Bool

source

ComponentLogging.clogf — Function

clogf(f::Function, logger, group, level; _module, file, line)

Like clog, but accepts a zero-argument function f that is only invoked if logging is enabled for the specified group and level. If f() returns nothing, no message is emitted. Non-tuple returns are converted to a tuple internally.

If @forward_logger is already used, the following forwarding signatures are available:

clogf(f, group, level; _module, file, line)

source

ComponentLogging.@forward_logger — Macro

@forward_logger logger

Define forwarding methods in the current module so you can call clog, clogf, clogenabled, set_log_level, and with_min_level without explicitly passing a logger each time.

logger may be either an AbstractLogger or a Base.RefValue{<:AbstractLogger}.

Example:

using ComponentLogging

const pkg_logger = Ref(ComponentLogger(...))
@forward_logger pkg_logger

clog(:core, 0, "hello")
clogf(:core, 0) do
    ("expensive ", 1 + 2)
end
set_log_level(:core, 1000)
with_min_level(2000) do
    # Temporarily raise the global minimum level (fast early rejection).
    clog(:core, 0, "suppressed by global min")
end

Note: Use this macro at module top-level.

source