Skip to main content

Log

This item is only intended to be used by the module's authors. Private

Provides a structured logging implementation for the Lyra library.

Design:

  • Callback-based: Instead of directly printing or sending logs, this module uses a callback function (logCallback) provided during logger creation. This allows the consuming application to decide how and where log messages are routed (e.g., print to console, send to an external service, store in memory).
  • Structured Context: Log messages include a context table. Loggers can be extended with additional context fields, which are automatically merged into every subsequent log message created by that logger instance or its descendants. This helps provide detailed, structured information for debugging and monitoring.
  • Log Levels: Supports standard log levels (fatal, error, warn, info, debug, trace). A global log level can be set using Log.setLevel to filter out messages below the desired severity.

Usage:

local Log = require(script.Parent.Log)

-- Set the global minimum log level (optional, defaults to "info")
Log.setLevel("debug")

-- Create a logger instance with a callback
local myLogger = Log.createLogger(function(logMessage)
	print(`[{logMessage.level}] {logMessage.message}`, logMessage.context)
end, { initialContext = "value" })

-- Log messages
myLogger:log("info", "User logged in", { userId = 123 })

-- Create a logger with extended context
local sessionLogger = myLogger:extend({ sessionId = "abc" })
sessionLogger:log("debug", "Session data loaded")
-- Output will include { initialContext = "value", sessionId = "abc", userId = 123 }
-- if logged via myLogger, or { initialContext = "value", sessionId = "abc" }
-- if logged via sessionLogger.

Types​

LogLevel​

enum
</>
type LogLevel = "fatal" | "error" | "warn" | "info" | "debug" | "trace"

Represents the different log levels available for logging messages.

LogMessage​

</>
interface LogMessage {
message: string--

The main content of the log message.

level: LogLevel--

The severity level of the message.

context: {[string]: any}?--

Optional table containing additional structured context.

}

Represents a log message sent to the logger's callback function.

Functions​

setLevel​

</>
Log.setLevel(
level: LogLevel--

The minimum log level to allow.

) → ()

Sets the global minimum log level. Messages with a severity lower than this level will be ignored by all loggers.

Errors

TypeDescription
stringThrows an error if the provided level is invalid.

createLogger​

</>
Log.createLogger(
logCallback: (logMessage: LogMessage) → (),--

The function that will be called for each log message that passes the level filter. This function receives the complete LogMessage object including merged context.

context: {[string]: any}?--

Optional initial context for this logger.

) → Logger--

A new Logger instance.

Factory function to create a new root Logger instance.

log​

</>
Log:log(
level: LogLevel,--

The severity level of the message.

message: string,--

The log message content.

context: {[string]: any}?--

Optional additional context specific to this log call.

) → ()

Logs a message if its level is at or above the globally set log level.

Merges the provided context table with the logger's persistent context before calling the configured _logCallback.

extend​

</>
Log:extend(
context: {[string]: any}--

The additional context fields to add.

) → Logger--

A new Logger instance with the extended context.

Creates a new Logger instance that inherits the parent's callback but has an extended context.

The new logger's context is a merged table containing the parent's context and the additional context provided here.

Show raw api
{
    "functions": [
        {
            "name": "setLevel",
            "desc": "Sets the global minimum log level.\nMessages with a severity lower than this level will be ignored by all loggers.",
            "params": [
                {
                    "name": "level",
                    "desc": "The minimum log level to allow.",
                    "lua_type": "LogLevel"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "string",
                    "desc": "Throws an error if the provided level is invalid."
                }
            ],
            "source": {
                "line": 105,
                "path": "src/Log.luau"
            }
        },
        {
            "name": "log",
            "desc": "Logs a message if its level is at or above the globally set log level.\n\nMerges the provided `context` table with the logger's persistent context\nbefore calling the configured `_logCallback`.",
            "params": [
                {
                    "name": "level",
                    "desc": "The severity level of the message.",
                    "lua_type": "LogLevel"
                },
                {
                    "name": "message",
                    "desc": "The log message content.",
                    "lua_type": "string"
                },
                {
                    "name": "context",
                    "desc": "Optional additional context specific to this log call.",
                    "lua_type": "{ [string]: any }?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 127,
                "path": "src/Log.luau"
            }
        },
        {
            "name": "extend",
            "desc": "Creates a new Logger instance that inherits the parent's callback\nbut has an extended context.\n\nThe new logger's context is a merged table containing the parent's context\nand the additional `context` provided here.",
            "params": [
                {
                    "name": "context",
                    "desc": "The additional context fields to add.",
                    "lua_type": "{ [string]: any }"
                }
            ],
            "returns": [
                {
                    "desc": "A new Logger instance with the extended context.",
                    "lua_type": "Logger"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 167,
                "path": "src/Log.luau"
            }
        },
        {
            "name": "createLogger",
            "desc": "Factory function to create a new root Logger instance.",
            "params": [
                {
                    "name": "logCallback",
                    "desc": "The function that will be called for each log message that passes the level filter. This function receives the complete `LogMessage` object including merged context.",
                    "lua_type": "(logMessage: LogMessage) -> ()"
                },
                {
                    "name": "context",
                    "desc": "Optional initial context for this logger.",
                    "lua_type": "{ [string]: any }?"
                }
            ],
            "returns": [
                {
                    "desc": "A new Logger instance.",
                    "lua_type": "Logger"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 189,
                "path": "src/Log.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "LogLevel",
            "desc": "Represents the different log levels available for logging messages.",
            "lua_type": "\"fatal\" | \"error\" | \"warn\" | \"info\" | \"debug\" | \"trace\"",
            "tags": [
                "enum"
            ],
            "source": {
                "line": 51,
                "path": "src/Log.luau"
            }
        },
        {
            "name": "LogMessage",
            "desc": "Represents a log message sent to the logger's callback function.",
            "fields": [
                {
                    "name": "message",
                    "lua_type": "string",
                    "desc": "The main content of the log message."
                },
                {
                    "name": "level",
                    "lua_type": "LogLevel",
                    "desc": "The severity level of the message."
                },
                {
                    "name": "context",
                    "lua_type": "{ [string]: any }?",
                    "desc": "Optional table containing additional structured context."
                }
            ],
            "source": {
                "line": 62,
                "path": "src/Log.luau"
            }
        }
    ],
    "name": "Log",
    "desc": "Provides a structured logging implementation for the Lyra library.\n\n**Design:**\n- **Callback-based:** Instead of directly printing or sending logs, this module\n  uses a callback function (`logCallback`) provided during logger creation. This\n  allows the consuming application to decide how and where log messages are routed\n  (e.g., print to console, send to an external service, store in memory).\n- **Structured Context:** Log messages include a `context` table. Loggers can be\n  `extend`ed with additional context fields, which are automatically merged into\n  every subsequent log message created by that logger instance or its descendants.\n  This helps provide detailed, structured information for debugging and monitoring.\n- **Log Levels:** Supports standard log levels (`fatal`, `error`, `warn`, `info`,\n  `debug`, `trace`). A global log level can be set using `Log.setLevel` to filter\n  out messages below the desired severity.\n\n**Usage:**\n```lua\nlocal Log = require(script.Parent.Log)\n\n-- Set the global minimum log level (optional, defaults to \"info\")\nLog.setLevel(\"debug\")\n\n-- Create a logger instance with a callback\nlocal myLogger = Log.createLogger(function(logMessage)\n\tprint(`[{logMessage.level}] {logMessage.message}`, logMessage.context)\nend, { initialContext = \"value\" })\n\n-- Log messages\nmyLogger:log(\"info\", \"User logged in\", { userId = 123 })\n\n-- Create a logger with extended context\nlocal sessionLogger = myLogger:extend({ sessionId = \"abc\" })\nsessionLogger:log(\"debug\", \"Session data loaded\")\n-- Output will include { initialContext = \"value\", sessionId = \"abc\", userId = 123 }\n-- if logged via myLogger, or { initialContext = \"value\", sessionId = \"abc\" }\n-- if logged via sessionLogger.\n```",
    "private": true,
    "source": {
        "line": 43,
        "path": "src/Log.luau"
    }
}