Skip to main content

Logger

Responsible for creating Records to be filtered and emit to Handlers.

Types

Filter

</>
type Filter = (Record) → (boolean)

A function which accepts a record to consider and returns a boolean indicating whether the record should be processed. It is called by Logger:filter and Handler:filter.

Properties

logging

since 0.1.0
</>
Logger.logging: Logging

The logging module in which this logger was created.

name

Hierarchy
since 0.1.0
</>
Logger.name: string

The name of this logger to be considered when working with logger hierarchies.

parent

Hierarchy
since 0.1.0
</>
Logger.parent: Logger

The parent logger whose level shall be deferred to when this logger's level is Level.NotSet (see Logger:getEffectiveLevel). [Records] emit by this logger are emit to the parent logger if Logger.propagate is true.

Loggers at the top level, e.g. Logging:getLogger("MyModule"), have the root logger as their parent. The root logger does not have a parent.

propagate

Hierarchy
since 0.1.0
</>
Logger.propagate: boolean

Indicates whether records should be handled by the Logger.parent, if it exists.

children

Hierarchy
since 0.1.0
</>
Logger.children: table

Maps the child Logger.names to the child Loggers themselves.

level

Filtering
since 0.1.0
</>
Logger.level: Level

The level of this logger. Use Logger:getEffectiveLevel when considering a logger's level.

filters

Filtering
since 0.1.0
</>
Logger.filters: table

A set of Filters added to this logger with Logger:addFilter.

handlers

Handling
since 0.1.0
</>
Logger.handlers: table

A set of Handlers added to this logger with Logger:addHandler.

Functions

getFullName

Hierarchy
since 0.1.0
</>
Logger:getFullName() → string

Returns the names of all ancestors of a logger and the logger's name itself, concatenated by periods, e.g. MyFightingGame.Players.DataStores. The value returned by this function can be sent to Logging:getLogger to retrieve the same logger.

getChild

Hierarchy
since 0.1.0
</>
Logger:getChild(childName: string) → ()

Gets a child logger with the given name, creating it if it does not exist. If the given name contains a period, the logger returned is the child whose name appears after the period, i.e. logger:getChild("MyFightingGame.Players") is the same as logger:getChild("MyFightingGame"):getChild("Players")

setLevel

Filtering
since 0.1.0
</>
Logger:setLevel(level: Level) → ()

Sets the lowest level of Records that this logger will emit to its handlers.

getEffectiveLevel

Filtering
since 0.1.0
</>
Logger:getEffectiveLevel() → Level

Returns the level of this logger, or if it is Level.NotSet, the effective level of the Logger.parent.

isEnabledFor

Filtering
since 0.1.0
</>
Logger:isEnabledFor(level: Level) → ()

Returns whether this logger will filter Records with the given Level according to its Logger:getEffectiveLevel.

addFilter

Filtering
since 0.1.0
</>
Logger:addFilter(filter: Filter) → ()

Adds a Filter to this logger.

removeFilter

Filtering
since 0.1.0
</>
Logger:removeFilter(filter: Filter) → ()

Removes a Filter from this logger.

filter

Filtering
since 0.1.0
</>
Logger:filter(record: Record) → boolean

Checks if the level of the given record using Logger:isEnabledFor. If it is, each filter added by Logger:addFilter is called in turn. If any filter function returns false or nil, this function returns false. Otherwise, this function returns true.

addHandler

Handling
since 0.1.0
</>
Logger:addHandler(handler: Handler) → ()

Adds a Handler to this logger. If a function is provided instead, a FuncHandler is created to wrap it.

removeHandler

Handling
since 0.1.0
</>
Logger:removeHandler(handler: Handler) → ()

Removes a Handler from this logger. If a function is provided, a FuncHandler with the given function is searched for and removed.

newRecord

Logging
since 0.1.0
</>
Logger:newRecord(
level: Level,
message: RecordMessage,
...: any
) → Record

Creates a Record with the provided arguments.

log

Logging
since 0.1.0
</>
Logger:log(
level: Level,
message: RecordMessage,
...: any
) → Record

Create a Record using Logger:newRecord with the provided arguments. Then, calls Logger:filter, and if it passes, Logger:emit. Returns the newly created record.

emit

Logging
since 0.1.0
</>
Logger:emit(record: Record) → ()

Invokes each of the logger's Handlers with the given Record. Then, if Logger.propagate is true, the record is emit on the Logger.parent.

debug

Logging
since 0.1.0
</>
Logger:debug(
message: RecordMessage,
...: any
) → Record

Invokes Logger:log with the level of the record set to Level.Debug.

info

Logging
since 0.1.0
</>
Logger:info(
message: RecordMessage,
...: any
) → Record

Invokes Logger:log with the level of the record set to Level.Info.

warning

Logging
since 0.1.0
</>
Logger:warning(
message: RecordMessage,
...: any
) → Record

Invokes Logger:log with the level of the record set to Level.Warning.

error

Logging
since 0.1.0
</>
Logger:error(
message: RecordMessage,
...: any
) → Record

Invokes Logger:log with the level of the record set to Level.Error.

critical

Logging
since 0.1.0
</>
Logger:critical(
message: RecordMessage,
...: any
) → Record

Invokes Logger:log with the level of the record set to Level.Critical.

wrap

Sugar
since 0.1.0
</>
Logger:wrap(callOriginal: boolean) → function,function

Returns two functions which wrap the built-in print and wrap globals. If callOriginal is true, the original global functions are called after logging.

pcall

Sugar
since 0.1.0
</>
Logger:pcall(
func: function,
...: any
) → any

Works just like the global pcall, with the addition of logging an Level.Error if the function errors.

xpcall

Sugar
since 0.1.0
</>
Logger:xpcall(
func: function,
errorHandler: function,
...: any
) → any

Works just like the global xpcall, with the addition of logging an Level.Error if the function errors.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new logger of the given `name` within the given [Logging] module.\nShould not be used directly. Instead, call [Logging:getLogger] or [Logger:getChild] which\nproperly construct the logger hierarchy.",
            "params": [
                {
                    "name": "logging",
                    "desc": "",
                    "lua_type": "Logging"
                },
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "[Record]"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Logger"
                }
            ],
            "function_type": "static",
            "since": "0.1.0",
            "private": true,
            "source": {
                "line": 102,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "getFullName",
            "desc": "Returns the names of all ancestors of a logger and the logger's name itself, concatenated by\nperiods, e.g. `MyFightingGame.Players.DataStores`. The value returned by this function can\nbe sent to [Logging:getLogger] to retrieve the same logger.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "tags": [
                "Hierarchy"
            ],
            "since": "0.1.0",
            "source": {
                "line": 129,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "getChild",
            "desc": "Gets a child logger with the given name, creating it if it does not exist.\nIf the given name contains a period, the logger returned is the child whose name appears\nafter the period, i.e. `logger:getChild(\"MyFightingGame.Players\")` is the same as\n`logger:getChild(\"MyFightingGame\"):getChild(\"Players\")`",
            "params": [
                {
                    "name": "childName",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Hierarchy"
            ],
            "since": "0.1.0",
            "source": {
                "line": 147,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "setLevel",
            "desc": "Sets the lowest level of [Record]s that this logger will emit to its handlers.",
            "params": [
                {
                    "name": "level",
                    "desc": "",
                    "lua_type": "Level"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 173,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "getEffectiveLevel",
            "desc": "Returns the level of this logger, or if it is [Level.NotSet], the effective level of the [Logger.parent].",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Level"
                }
            ],
            "function_type": "method",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 190,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "isEnabledFor",
            "desc": "Returns whether this logger will filter [Record]s with the given [Level] according to its [Logger:getEffectiveLevel].",
            "params": [
                {
                    "name": "level",
                    "desc": "",
                    "lua_type": "Level"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 201,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "addFilter",
            "desc": "Adds a [Filter] to this logger.",
            "params": [
                {
                    "name": "filter",
                    "desc": "",
                    "lua_type": "Filter"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 215,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "removeFilter",
            "desc": "Removes a [Filter] from this logger.",
            "params": [
                {
                    "name": "filter",
                    "desc": "",
                    "lua_type": "Filter"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 226,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "filter",
            "desc": "Checks if the level of the given record using [Logger:isEnabledFor].\nIf it is, each filter added by [Logger:addFilter] is called in turn.\nIf any filter function returns false or nil, this function returns false.\nOtherwise, this function returns true.",
            "params": [
                {
                    "name": "record",
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 240,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "addHandler",
            "desc": "Adds a [Handler] to this logger. If a function is provided instead, a [FuncHandler] is created to wrap it.",
            "params": [
                {
                    "name": "handler",
                    "desc": "",
                    "lua_type": "Handler"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Handling"
            ],
            "since": "0.1.0",
            "source": {
                "line": 258,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "removeHandler",
            "desc": "Removes a [Handler] from this logger. If a function is provided, a [FuncHandler] with the given function is searched for and removed.",
            "params": [
                {
                    "name": "handler",
                    "desc": "",
                    "lua_type": "Handler"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Handling"
            ],
            "since": "0.1.0",
            "source": {
                "line": 274,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "newRecord",
            "desc": "Creates a [Record] with the provided arguments.",
            "params": [
                {
                    "name": "level",
                    "desc": "",
                    "lua_type": "Level"
                },
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 299,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "log",
            "desc": "Create a [Record] using [Logger:newRecord] with the provided arguments.\nThen, calls [Logger:filter], and if it passes, [Logger:emit]. Returns the\nnewly created record.",
            "params": [
                {
                    "name": "level",
                    "desc": "",
                    "lua_type": "Level"
                },
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 314,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "emit",
            "desc": "Invokes each of the logger's [Handler]s with the given [Record]. Then,\nif [Logger.propagate] is true, the record is emit on the [Logger.parent].",
            "params": [
                {
                    "name": "record",
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 329,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "debug",
            "desc": "Invokes [Logger:log] with the level of the record set to [Level.Debug].",
            "params": [
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 352,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "info",
            "desc": "Invokes [Logger:log] with the level of the record set to [Level.Info].",
            "params": [
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 365,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "warning",
            "desc": "Invokes [Logger:log] with the level of the record set to [Level.Warning].",
            "params": [
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 377,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "error",
            "desc": "Invokes [Logger:log] with the level of the record set to [Level.Error].",
            "params": [
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 390,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "critical",
            "desc": "Invokes [Logger:log] with the level of the record set to [Level.Critical].",
            "params": [
                {
                    "name": "message",
                    "desc": "",
                    "lua_type": "RecordMessage"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Record"
                }
            ],
            "function_type": "method",
            "tags": [
                "Logging"
            ],
            "since": "0.1.0",
            "source": {
                "line": 402,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "wrap",
            "desc": "Returns two functions which wrap the built-in `print` and `wrap` globals.\nIf `callOriginal` is true, the original global functions are called after\nlogging.",
            "params": [
                {
                    "name": "callOriginal",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "function, function"
                }
            ],
            "function_type": "method",
            "tags": [
                "Sugar"
            ],
            "since": "0.1.0",
            "source": {
                "line": 415,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "pcall",
            "desc": "Works just like the global `pcall`, with the addition of logging an [Level.Error] if the function errors.",
            "params": [
                {
                    "name": "func",
                    "desc": "",
                    "lua_type": "function"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "function_type": "method",
            "tags": [
                "Sugar"
            ],
            "since": "0.1.0",
            "source": {
                "line": 446,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "xpcall",
            "desc": "Works just like the global `xpcall`, with the addition of logging an [Level.Error] if the function errors.",
            "params": [
                {
                    "name": "func",
                    "desc": "",
                    "lua_type": "function"
                },
                {
                    "name": "errorHandler",
                    "desc": "",
                    "lua_type": "function"
                },
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "function_type": "method",
            "tags": [
                "Sugar"
            ],
            "since": "0.1.0",
            "source": {
                "line": 463,
                "path": "Logging/Logger.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "logging",
            "desc": "The logging module in which this logger was created.",
            "lua_type": "Logging",
            "since": "0.1.0",
            "source": {
                "line": 28,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "name",
            "desc": "The name of this logger to be considered when working with logger hierarchies.",
            "lua_type": "string",
            "tags": [
                "Hierarchy"
            ],
            "since": "0.1.0",
            "source": {
                "line": 36,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "parent",
            "desc": "The parent logger whose level shall be deferred to when this logger's level is [Level.NotSet]\n(see [Logger:getEffectiveLevel]). [Records] emit by this logger are emit to the parent logger\nif [Logger.propagate] is true.\n\nLoggers at the top level, e.g. `Logging:getLogger(\"MyModule\")`, have the root logger as their parent.\nThe root logger does not have a parent.",
            "lua_type": "Logger",
            "tags": [
                "Hierarchy"
            ],
            "since": "0.1.0",
            "source": {
                "line": 49,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "propagate",
            "desc": "Indicates whether records should be handled by the [Logger.parent], if it exists.",
            "lua_type": "boolean",
            "tags": [
                "Hierarchy"
            ],
            "since": "0.1.0",
            "source": {
                "line": 57,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "children",
            "desc": "Maps the child [Logger.name]s to the child [Logger]s themselves.",
            "lua_type": "table",
            "tags": [
                "Hierarchy"
            ],
            "since": "0.1.0",
            "source": {
                "line": 65,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "level",
            "desc": "The level of this logger. Use [Logger:getEffectiveLevel] when considering\na logger's level.",
            "lua_type": "Level",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 74,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "filters",
            "desc": "A set of [Filter]s added to this logger with [Logger:addFilter].",
            "lua_type": "table",
            "tags": [
                "Filtering"
            ],
            "since": "0.1.0",
            "source": {
                "line": 82,
                "path": "Logging/Logger.lua"
            }
        },
        {
            "name": "handlers",
            "desc": "A set of [Handler]s added to this logger with [Logger:addHandler].",
            "lua_type": "table",
            "tags": [
                "Handling"
            ],
            "since": "0.1.0",
            "source": {
                "line": 90,
                "path": "Logging/Logger.lua"
            }
        }
    ],
    "types": [
        {
            "name": "Filter",
            "desc": "A function which accepts a record to consider and returns a boolean indicating whether\nthe record should be processed. It is called by [Logger:filter] and [Handler:filter].",
            "lua_type": "(Record) -> (boolean)",
            "source": {
                "line": 21,
                "path": "Logging/Logger.lua"
            }
        }
    ],
    "name": "Logger",
    "desc": "Responsible for creating [Record]s to be filtered and emit to [Handler]s.",
    "source": {
        "line": 9,
        "path": "Logging/Logger.lua"
    }
}