This library provides facilities to log debug output in the background without running the risk of it showing in the chat output. It can also be very helpful in debugging issues out in the wild, since it will store the output into its saved variable file. It will automatically log information about the current client. During startup the library will use the settings overrides defined in StartUpConfig.lua, until the saved variables become available.
The log output can be inspected with the help of the
DebugLogViewer add-on or the external
Log Viewer.
Features
Client Information
The library will automatically log the following information about a character on login:
- account name - in case you play with multiple accounts and that is somehow causing issues (e.g. with the saved variables)
- character name - in case the problem occurs due to switching characters or due to some special characters in the name
- login time - in case a problem occurs a fixed time after logging in on the character
- client version - hope that doesn't need an explanation
- mega server - in case of server specific issues
- service type - steam or non-steam in case that makes a difference
- UI type - keyboard or console UI is quite an important detail
- ESO+ - changes how some APIs react
- language - in case it is some localization problem
- out of date checkbox state - good to know when someone has an issue with some add-on not loading
- add-on count - how many are active and how many are installed
- add-on load events - this gives information about the load order of your add-ons, the loaded add-on version and which subdirectory of the add-on folder it was loaded from
In addition it will also log Lua errors, add-on output done via the in-game debug functions
d(),
df() and
CHAT_SYSTEM:AddMessage(), alert messages in the error category, loading screens and more based on the configuration in StartUpConfig.lua.
Stack Traces
Usually only Lua errors contain a stack trace, but the library can be configured to log the stack trace for any message. Due to the fact that saved settings are not available until after an add-on has fully loaded, the library will default to log everything during login and switch to the configured settings afterwards.
Logger Class
Authors can create a logger object which can be used to log messages of different severity (debug/info/warning/error). Those messages will be marked with the tag passed to the logger on creation and can be easily filtered that way.
A logger can create any number of sub-instances which will use the original tag with another part appended. This can be useful for big add-ons with many components, or when some very verbose logging should be disabled for a release version without having to remove all calls to the logger.
Quick Start
Add LibDebugLogger as a dependency to your add-on manifest:
Code:
## DependsOn: LibDebugLogger>=180
Afterwards you can create a logger instance and start logging messages like so:
Lua Code:
local logger = LibDebugLogger("MyAddon")
logger:Debug("A debug message")
logger:Info("An", "info", "message") -- multiple arguments are passed through tostring and concatenated with a space in between
logger:Warn("A %s message: %d", "formatted", 123) -- if the first parameter contains formatting strings, the logger will pass all arguments through string.format instead
local subLogger = logger:Create("verbose") -- this will create a separate logger with a combined tag "MyAddon/verbose".
subLogger:SetEnabled(false) -- turn the new logger off
subLogger:Error("An error message") -- this won't show up
Settings
The /debuglogger slash command can be used to configure what should get logged or show the current settings when no value is passed to a setting.
/debuglogger stack <on/off> - when turned on, the library will log the stack trace for the logger call. Can be very useful to figure out where a log is coming from.
/debuglogger level <d(ebug)/i(nfo)/w(arning)/e(rror)> - determines the minimum severity for logs to be stored
/debuglogger clear - will delete all stored logs
LibDebugLogger will automatically remove old logs after one day, or when the total amount surpasses 11k entries.
API Reference
LibDebugLogger.DEFAULT_SETTINGS
This constant contains the default settings for the library. The contained values should not be changed.
LibDebugLogger.TAG_INGAME
This constant contains the tag that is used to log messages that are generated by in-game methods (Lua Errors, chat debug output, alerts).
Log Levels
The values of the available log levels are stored in the following constants:
- LibDebugLogger.LOG_LEVEL_VERBOSE = "V"
- LibDebugLogger.LOG_LEVEL_DEBUG = "D"
- LibDebugLogger.LOG_LEVEL_INFO = "I"
- LibDebugLogger.LOG_LEVEL_WARNING = "W"
- LibDebugLogger.LOG_LEVEL_ERROR = "E"
The log levels are also stored in the LibDebugLogger.LOG_LEVELS array in order of their severity.
There are also two mappings LibDebugLogger.LOG_LEVEL_TO_STRING and LibDebugLogger.STR_TO_LOG_LEVEL which can be used to convert the level values into untranslated lowercase strings and back.
The different log levels serve different purposes which authors should keep in mind when they add log output.
- LOG_LEVEL_VERBOSE is not logged unless explicitly white-listed in the StartUpConfig.lua. It should be used for messages that are printed very often and are not of much interest to other parties.
- LOG_LEVEL_DEBUG is not logged by default and can be used for anything that helps identifying a problem, but is not of interest during regular operation.
- LOG_LEVEL_INFO is the default log level and should be used to log messages that give a rough idea of the flow of events during regular operation. It is also used for logging d() messages.
- LOG_LEVEL_WARNING should be used to log messages that could potentially lead to errors. Ingame alert messages of the UI_ALERT_CATEGORY_ERROR are logged as warnings.
- LOG_LEVEL_ERROR should usually not be used by addons, except when they suppress the ingame error message via pcall. UI errors are otherwise automatically logged with this level.
Log Entry Indices
A log entry is a numerically indexed table with the following values:
- raw timestamp in milliseconds
- human readable time
- occurrence count
- log level
- tag
- message
- stack trace (optional)
To use the values one can either use the unpack function and assign them to variables, or directly access them with the following index constants:
- LibDebugLogger.ENTRY_TIME_INDEX
- LibDebugLogger.ENTRY_FORMATTED_TIME_INDEX
- LibDebugLogger.ENTRY_OCCURENCES_INDEX
- LibDebugLogger.ENTRY_LEVEL_INDEX
- LibDebugLogger.ENTRY_TAG_INDEX
- LibDebugLogger.ENTRY_MESSAGE_INDEX
- LibDebugLogger.ENTRY_STACK_INDEX
- LibDebugLogger.ENTRY_ERROR_CODE_INDEX
Create
This function will return an instance of a logger. Anything logged via that instance will automatically contain the tag for easy identification.
Code:
local logger = LibDebugLogger.Create("MyAddon")
or
Code:
local logger = LibDebugLogger:Create("MyAddon")
or
Code:
local logger = LibDebugLogger("MyAddon")
Logger:Create
Convenience method to create a new instance of the logger with a combined tag. Can be used to separate logs from different files. Anything logged via that instance will automatically contain the parent tag and the child tag separated by a slash (e.g. MyAddon/SomeFile).
Code:
local subLogger = logger:Create("SomeFile")
Logger:SetEnabled
Setter to turn this logger off, so it no longer adds anything to the log when one of its log methods is called.
Code:
logger:SetEnabled(false)
Logger:SetMinLevelOverride
Setter to define a non-persistent override for the minimum log level from the global configuration. Passing nil clears the override value.
This method is intended to allow authors to provide users with a way to temporarily enable debug logging on a per-addon basis (e.g. via a LAM button).
Code:
logger:SetMinLevelOverride(LibDebugLogger.LOG_LEVEL_DEBUG)
Logger:SetLogTracesOverride
Setter to define a non-persistent override for the stack trace logging from the global configuration. Passing nil clears the override value.
This method is intended to allow authors to provide users with a way to temporarily enable debug logging on a per-addon basis (e.g. via a LAM button).
Code:
logger:SetLogTracesOverride(true)
Logger:Log
Method to log messages with the passed log level. The first argument has to be a valid log level. If the second argument is a formatting string, the method will call string.format, otherwise each argument will get passed through tostring and concatenated with a space.
Code:
logger:Log(LibDebugLogger.LOG_LEVEL_DEBUG, "My formatted message: %s", "some text")
logger:Log(LibDebugLogger.LOG_LEVEL_DEBUG, "My", "combined", "message")
Logger:Verbose
Method to log messages with the verbose log level. See Log method for details on how messages are formatted. Verbose messages are not logged unless explicitly white-listed in StartUpConfig.lua.
Logger:Debug
Method to log messages with the debug log level. See Log method for details on how messages are formatted.
Logger:Info
Method to log messages with the info log level. See Log method for details on how messages are formatted.
Logger:Warn
Method to log messages with the warning log level. See Log method for details on how messages are formatted.
Logger:Error
Method to log messages with the error log level. See Log method for details on how messages are formatted.
SESSION_START_TIME
Contains the time when the client was started in milliseconds.
Code:
local sessionStartTime = LibDebugLogger.SESSION_START_TIME
UI_LOAD_START_TIME
Contains the approximate time when the UI has started loading in milliseconds. There is currently no way to get the real time, so instead this is just the time when LibDebugLogger.lua is executed first, which can be happen several seconds after the actual UI load start. Since the purpose of this function is to provide a way to discern log messages that have been created in the current UI load, this is fine.
Code:
local uiLoadStartTime = LibDebugLogger.UI_LOAD_START_TIME
IsTraceLoggingEnabled
Returns true if the library is set to capture stack traces for all messages.
Code:
local isTraceLoggingEnabled = LibDebugLogger:IsTraceLoggingEnabled()
SetTraceLoggingEnabled
Sets stack traces capturing for all messages enabled or disabled.
Code:
LibDebugLogger:SetTraceLoggingEnabled(enabled)
GetMinLogLevel
Returns the minimum log level.
Code:
local minLogLevel = LibDebugLogger:GetMinLogLevel()
SetMinLogLevel
Sets the minimum log level. Has to be one of the values in the LOG_LEVELS constant.
Code:
LibDebugLogger:SetMinLogLevel(level)
GetLog
Returns the current log table.
Code:
LibDebugLogger:GetLog()
ToggleFormattingErrors
When toggled on, the log handler will append errors in case the first argument was interpreted as a formatting string, but the subsequent call to string.format failed. This is purely for the convenience of authors who try to debug their log output and as such it doesn't have a corresponding setting.
Intended use is either via "/script d(LibDebugLogger:ToggleFormattingErrors())" or in StartUpConfig.lua
Returns the new state.
Code:
LibDebugLogger:ToggleFormattingErrors()
ClearLog
Clears the log by creating a new table.
Code:
LibDebugLogger:ClearLog()
SetBlockChatOutputEnabled
Function to block showing chat debug messages created via d(), df() or CHAT_SYSTEM:AddMessage() in the regular chat. Can be used by other add-ons that display the log content, to avoid having the messages show up twice on screen. Should be called as early as possible.
Code:
LibDebugLogger:SetBlockChatOutputEnabled(enabled)
IsBlockChatOutputEnabled
Returns true if chat debug messages are blocked from showing in chat.
Code:
local isBlocked = LibDebugLogger:IsBlockChatOutputEnabled()
CombineSplitStringIfNeeded
This method rebuilds the input string in case it has been split up to circumvent the saved variables string length limit.
Code:
input = LibDebugLogger.CombineSplitStringIfNeeded(input)
RegisterCallback
The library fires callbacks whenever the log is modified. Callbacks should be as lightweight as possible. If you plan to use expensive calls, defer the execution with zo_callLater!
Callback names are available via the LibDebugLogger.callback table and are defined in Callbacks.lua.
Code:
LibDebugLogger:RegisterCallback(callbackName, callback)
callback.LOG_CLEARED
This callback is fired when the log is wiped by the user or an addon. Passes the reference to the empty log.
Code:
LibDebugLogger:RegisterCallback(LibDebugLogger.callback.LOG_CLEARED, function(log)
-- do something
end)
callback.LOG_PRUNED
This callback is fired after a new message was added and the log contains too many entries.
This pruning is necessary to prevent the log from growing too large to be loaded on login.
Pruning will create a new log table and the startIndex passed to the callback is the first index in the old log table that will be kept in the new log.
Code:
LibDebugLogger:RegisterCallback(LibDebugLogger.callback.LOG_PRUNED, function(startIndex)
-- do something
end)
callback.LOG_ADDED
This callback is fired whenever a log entry is added. The entry parameter is the data as stored in the log and wasDuplicate is true when the entry had the same message, level and stack trace as the previous one and only the time and occurrence count was adjusted.
Code:
LibDebugLogger:RegisterCallback(LibDebugLogger.callback.LOG_CLEARED, function(entry, wasDuplicate)
-- do something
end)
06/06/23, 02:00 PM
