Emits a log record at a specific level.
@eryx/logging Module
JSON
Structured, hierarchical logging for Luau applications.
This module provides:
- named loggers with parent/child inheritance (
app,app.http, ...) - leveled logging (
debug..critical) - handler-based output routing
- optional source metadata capture
The root logger is "" and includes a default ConsoleHandler.
local logging = require("@eryx/logging")
logging.config({
level = "info",
})
local log = logging.getLogger("app")
log:info("server started", { port = 8080 })
Summary
Classes
_state: LoggerState
Functions
API Reference
Classes
Logger
Implements: LoggerData
Properties
_state: LoggerState
Logger:log
Parameters
Level name ("debug", "warn", ...) or numeric level.
Human-readable log message.
Optional structured attributes merged into the record.
Returns
true when at least one handler emitted the record.
Logger:debug
Logs a record at debug level.
Parameters
Returns
true when at least one handler emitted the record.
Logger:info
Logs a record at info level.
Parameters
Returns
true when at least one handler emitted the record.
Logger:warning
Logs a record at warning level.
Parameters
Returns
true when at least one handler emitted the record.
Logger:warn
Logs a record at warning level (alias for Logger.warning).
Parameters
Returns
true when at least one handler emitted the record.
Logger:error
Logs a record at error level.
Parameters
Returns
true when at least one handler emitted the record.
Logger:critical
Logs a record at critical level.
Parameters
Returns
true when at least one handler emitted the record.
Logger:isEnabledFor
Checks whether the logger is enabled for the provided level.
Parameters
Level name or numeric level.
Returns
true if records at this level would pass logger-level gating.
Logger:setLevel
Sets or clears this logger's explicit level.
Pass nil to clear the override and inherit from parents/root.
Parameters
Optional level override for this logger.
Returns
Self, for chaining.
Logger:addHandler
Adds a handler directly to this logger.
Parameters
A handler implementing the logging handler contract.
Returns
The normalized handler that was added.
Logger:removeHandler
Removes a handler from this logger.
Parameters
The handler instance to remove.
Returns
true when removed, false when not found.
Logger:clearHandlers
Clears all handlers attached to this logger.
@param none
Logger:clearHandlers() → ()
Logger:child
Creates or retrieves a child logger.
Child names are joined with . (for example app + http -> app.http).
When context is provided, the returned child logger includes that context.
Parameters
Child segment to append to this logger name.
Optional context merged into all child log records.
Returns
Child logger instance.
Logger:withContext
Returns a logger view with additional bound context.
Context is merged with per-call attrs, where per-call attrs win on conflicts.
Parameters
Structured attributes to bind to this logger.
Returns
A new logger view sharing the same logger state.
Logger:setPropagation
Enables or disables handler propagation to parent loggers.
Parameters
When false, dispatch stops at this logger.
Returns
Self, for chaining.
Logger:closeHandlers
Invokes close() on each handler attached to this logger.
Errors from handler close operations are suppressed.
@param none
Logger:closeHandlers() → ()
Functions
logging.parseLevel
Parses a level input into its numeric representation.
Supports canonical names ("debug", "warning", ...), alias "warn",
and raw numeric values.
Parameters
Level name/alias or numeric value.
Returns
Numeric level value used for comparisons.
logging.getLogger
Returns a logger by name, creating it if needed.
Logger names are hierarchical with dot-separated segments.
Omit the name (or pass "") to retrieve the root logger.
Parameters
Optional logger name (for example "app.http").
Returns
Logger instance bound to the requested name.
logging.config
Configures global logging behavior.
When reset is true, logger overrides/handlers are reset to defaults.
The root logger is reset to info level with the default console handler.
Parameters
Optional logging configuration.
logging.addHandler
Adds a handler to the root logger.
Root handlers receive records from all propagating child loggers.
Parameters
A handler implementing the logging handler contract.
Returns
The normalized handler that was added.
logging.removeHandler
Removes a handler from the root logger.
Parameters
The handler instance to remove.
Returns
true when removed, false when not found.
logging.clearHandlers
Clears all handlers from the root logger.
@param none
logging.clearHandlers() → ()
Types
LoggingConfig
type LoggingConfig = { level: LevelInput?, captureSource: boolean?, sourceDepth: number?, reset: boolean? }