Reference API Roblox

Engine API

Website

Related

Reference API Roblox

Logger

A named logger that emits structured log entries scoped to a hierarchical path.

This class is not replicated. Its interface does not cross the network boundary.
This class is not creatable. Instances of this class cannot be created with Instance.new.
Tags: [NotCreatable, NotReplicated]

Member index 9

HistoryMember
734FullPath: string
734Name: string
734Error(message: string, context: Dictionary = nil): null
734GetLogger(name: string): Logger
734Info(message: string, context: Dictionary = nil): null
734Log(messageType: MessageType, message: string, context: Dictionary = nil): null
734Output(message: string, context: Dictionary = nil): null
734Warn(message: string, context: Dictionary = nil): null
734MessageOut(message: string, messageType: MessageType, context: Dictionary)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Description

A Logger emits structured log entries that are tagged with a hierarchical name, letting you group related messages by subsystem or feature. Obtain a top-level logger from LogService:GetLogger(), then create nested child loggers with Logger:GetLogger(). Each logger has a short Logger.Name and a dot-joined Logger.FullPath built from its ancestry (for example a logger named Damage created from a logger named Combat has the full path Combat.Damage).

1
2
3
4
5
6
7
8
9
local LogService = game:GetService("LogService")

local combat = LogService:GetLogger("Combat")
local damage = combat:GetLogger("Damage")

print(damage.Name)      --> Damage
print(damage.FullPath)  --> Combat.Damage

damage:Info("Dealt {amount} damage to {target}", {amount = 25, target = "Goblin"})

Loggers behave the same as the structured logging methods on LogService: messages flow to the Output window, the Developer Console, and LogService.MessageOut, and are included in LogService:GetLogHistory() tagged with the logger's full path.

Hierarchy and Propagation

When a message is logged on a logger, its Logger.MessageOut event fires on that logger and on every ancestor up to the root. This lets you attach a listener on a parent logger to observe all messages emitted by its descendants. The message is emitted to the engine's output system exactly once, tagged with the originating logger's full path.

Template Syntax and Context

The logging methods accept the same {key} template placeholders and context tables as the structured logging methods on LogService. See LogService for details on template syntax and how context values are stored.

Lifetime

A logger remains valid as long as you hold a reference to it. Once all references to a logger (and its descendants) are released, it is reclaimed, and calling any method on a stale logger raises an error. The number of live loggers and the length of a logger's full path are both bounded; exceeding either limit raises an error from Logger:GetLogger().

Warning

This class might have unexpected or unreliable behavior and content might be truncated. Don't rely on contents of events and messages emitted by loggers for any important game logic.

History 10

Members 9

Error

Parameters (2)Default
messagestring
contextDictionarynil
Returns (1)
null

Logs a message at the MessageType.MessageError level, tagged with this logger's Logger.FullPath. Unlike LogService:Error(), this method emits an error-level log entry and returns normally; it does not throw. When a context table is provided, template placeholders like {key} in the message are replaced with the corresponding context values.

1
2
3
4
5
local LogService = game:GetService("LogService")
local logger = LogService:GetLogger("Network")

logger:Error("Request failed: {reason}", {reason = "timeout"})
-- Emits an error-level log; execution continues.
This function has a custom internal state. It may behave in a non-standard way.

History 1

Tags: [CustomLuaState]

FullPath

TypeDefault
string__api_dump_failed_to_create_class__

The full path of this logger, formed by joining the Logger.Name of each logger from the root down to this one with . separators. For a top-level logger the full path equals its name. Messages logged through this logger are tagged with this full path in LogService:GetLogHistory().

This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.

History 1

Tags: [ReadOnly, NotReplicated]

GetLogger

Parameters (1)
namestring
Returns (1)
Logger

Returns the child logger with the given name, creating it if it does not already exist. Calling this with the same name repeatedly returns the same logger instance for as long as a reference to it is held. The returned logger's Logger.FullPath is this logger's full path followed by . and name.

This method raises an error if the name is empty, contains a ., or contains control characters, if the resulting full path is too long, or if the maximum number of live loggers has been exceeded.

1
2
3
4
5
6
local LogService = game:GetService("LogService")

local network = LogService:GetLogger("Network")
local http = network:GetLogger("Http")

print(http.FullPath)  --> Network.Http
This function has a custom internal state. It may behave in a non-standard way.

History 1

Tags: [CustomLuaState]

Info

Parameters (2)Default
messagestring
contextDictionarynil
Returns (1)
null

Logs a message at the MessageType.MessageInfo level, tagged with this logger's Logger.FullPath. When a context table is provided, template placeholders like {key} in the message are replaced with the corresponding context values.

1
2
3
4
5
local LogService = game:GetService("LogService")
local logger = LogService:GetLogger("Combat")

logger:Info("Dealt {amount} damage", {amount = 42})
-- Output: "Dealt 42 damage"
This function has a custom internal state. It may behave in a non-standard way.

History 1

Tags: [CustomLuaState]

Log

Parameters (3)Default
messageTypeMessageType
messagestring
contextDictionarynil
Returns (1)
null

Logs a message at the specified MessageType level, tagged with this logger's Logger.FullPath. This is a general-purpose method that combines Output(), Info(), Warn(), and Error() into a single call with an explicit message type parameter. Unlike LogService:Log(), passing MessageType.MessageError emits an error-level log and returns normally rather than throwing.

1
2
3
4
local LogService = game:GetService("LogService")
local logger = LogService:GetLogger("Combat")

logger:Log(Enum.MessageType.MessageInfo, "Event {action}", {action = "spawn"})
This function has a custom internal state. It may behave in a non-standard way.

History 1

Tags: [CustomLuaState]

MessageOut

Parameters (3)
messagestring
messageTypeMessageType
contextDictionary

Fires whenever a message is logged through this logger or any logger beneath it in the hierarchy. Because a logged message fires MessageOut on the originating logger and each of its ancestors, a listener attached to a parent logger observes every message emitted by its descendants. The message parameter contains the fully rendered text (template placeholders already replaced), and the context parameter carries the structured key-value pairs when the message was logged with a context table; otherwise it is nil.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
local LogService = game:GetService("LogService")
local combat = LogService:GetLogger("Combat")

combat.MessageOut:Connect(function(message, messageType, context)
	print("[Combat]", message)
end)

-- A message logged on a descendant also fires the parent's MessageOut.
combat:GetLogger("Damage"):Info("Hit for {amount}", {amount = 10})
-- Prints: [Combat] Hit for 10

History 1

Name

TypeDefault
string__api_dump_failed_to_create_class__

The name of this logger as supplied to LogService:GetLogger() or Logger:GetLogger(). This is a single path segment and never contains a . character. Use Logger.FullPath for the complete dot-joined path.

This property is not replicated. Its interface does not cross the network boundary.
This property is read-only. Its value can be read, but it cannot be modified.

History 1

Tags: [ReadOnly, NotReplicated]

Output

Parameters (2)Default
messagestring
contextDictionarynil
Returns (1)
null

Logs a message at the MessageType.MessageOutput level, tagged with this logger's Logger.FullPath. When a context table is provided, template placeholders like {key} in the message are replaced with the corresponding context values, and the context is preserved as structured data for display in the Developer Console and Studio's Output window.

1
2
3
4
5
local LogService = game:GetService("LogService")
local logger = LogService:GetLogger("Shop")

logger:Output("Player {name} opened the shop", {name = "Alice"})
-- Output: "Player Alice opened the shop"
This function has a custom internal state. It may behave in a non-standard way.

History 1

Tags: [CustomLuaState]

Warn

Parameters (2)Default
messagestring
contextDictionarynil
Returns (1)
null

Logs a message at the MessageType.MessageWarning level, tagged with this logger's Logger.FullPath. When a context table is provided, template placeholders like {key} in the message are replaced with the corresponding context values.

1
2
3
4
5
local LogService = game:GetService("LogService")
local logger = LogService:GetLogger("Combat")

logger:Warn("Health low: {hp}", {hp = 5})
-- Output: "Health low: 5"
This function has a custom internal state. It may behave in a non-standard way.

History 1

Tags: [CustomLuaState]

Settings