(15 Kb)
Updated: 07/30/23 03:53 PM
File Info
Necrom (9.0.0)
Scribes of Fate (8.3.5)
Updated:07/30/23 03:53 PM
Created:02/26/19 10:22 AM
Monthly downloads:30,186
Total downloads:2,658,454
LibDebugLogger  Popular! (More than 5000 hits)
Version: 2.5.1
by: sirinsidiator [More]
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.


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:
## DependsOn: LibDebugLogger>=180
Afterwards you can create a logger instance and start logging messages like so:
Lua Code:
  1. local logger = LibDebugLogger("MyAddon")
  2. logger:Debug("A debug message")
  3. logger:Info("An", "info", "message") -- multiple arguments are passed through tostring and concatenated with a space in between
  4. 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
  5. local subLogger = logger:Create("verbose") -- this will create a separate logger with a combined tag "MyAddon/verbose".
  6. subLogger:SetEnabled(false) -- turn the new logger off
  7. subLogger:Error("An error message") -- this won't show up

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

This constant contains the default settings for the library. The contained values should not be changed.

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:
  1. raw timestamp in milliseconds
  2. human readable time
  3. occurrence count
  4. log level
  5. tag
  6. message
  7. 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_LEVEL_INDEX
  • LibDebugLogger.ENTRY_TAG_INDEX
  • LibDebugLogger.ENTRY_STACK_INDEX

This function will return an instance of a logger. Anything logged via that instance will automatically contain the tag for easy identification.
local logger = LibDebugLogger.Create("MyAddon")
local logger = LibDebugLogger:Create("MyAddon")
local logger = LibDebugLogger("MyAddon")
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).

local subLogger = logger:Create("SomeFile")
Setter to turn this logger off, so it no longer adds anything to the log when one of its log methods is called.

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).

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).

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.

logger:Log(LibDebugLogger.LOG_LEVEL_DEBUG, "My formatted message: %s", "some text")
logger:Log(LibDebugLogger.LOG_LEVEL_DEBUG, "My", "combined", "message")
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.

Method to log messages with the debug log level. See Log method for details on how messages are formatted.

Method to log messages with the info log level. See Log method for details on how messages are formatted.

Method to log messages with the warning log level. See Log method for details on how messages are formatted.

Method to log messages with the error log level. See Log method for details on how messages are formatted.

Contains the time when the client was started in milliseconds.
local sessionStartTime = LibDebugLogger.SESSION_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.
local uiLoadStartTime = LibDebugLogger.UI_LOAD_START_TIME
Returns true if the library is set to capture stack traces for all messages.
local isTraceLoggingEnabled = LibDebugLogger:IsTraceLoggingEnabled()
Sets stack traces capturing for all messages enabled or disabled.
Returns the minimum log level.
local minLogLevel = LibDebugLogger:GetMinLogLevel()
Sets the minimum log level. Has to be one of the values in the LOG_LEVELS constant.
Returns the current log table.
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.
Clears the log by creating a new table.
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.
Returns true if chat debug messages are blocked from showing in chat.
local isBlocked = LibDebugLogger:IsBlockChatOutputEnabled()
This method rebuilds the input string in case it has been split up to circumvent the saved variables string length limit.
input = LibDebugLogger.CombineSplitStringIfNeeded(input)
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.
LibDebugLogger:RegisterCallback(callbackName, callback)
This callback is fired when the log is wiped by the user or an addon. Passes the reference to the empty log.
LibDebugLogger:RegisterCallback(LibDebugLogger.callback.LOG_CLEARED, function(log)
    -- do something
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.
LibDebugLogger:RegisterCallback(LibDebugLogger.callback.LOG_PRUNED, function(startIndex)
    -- do something
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.
LibDebugLogger:RegisterCallback(LibDebugLogger.callback.LOG_CLEARED, function(entry, wasDuplicate)
    -- do something
- fixed error when launching game through epic store

- added preliminary support for storing newly introduced errorCode (NOTE: stacktrace can now be an empty string instead of nil)
- updated for Necrom

- added a warning when baseobjects have been modified with a __call meta method
- renamed LibDebugLogger.lua to StartUp.lua to avoid people mistaking it for the saved variable file

- added optional feature to append the stacktrace of the registation to any stacktrace logged inside a zo_callLater call (enabled via StartUpConfig.lua)
- added optional capture of stacktraces for "TopLevelControl cannot be parented to any control but GuiRoot" errors where possible (enabled together with the previous new feature)
- added optional logging of latency, fps and memory usage every 10 seconds (enabled via StartUpConfig.lua)
- added flag to StartUpConfig.lua to ignore saved settings
- renamed StartUpConfig.lua to StartUpConfig.example.lua and uncommented settings so users can simply rename the file to enable full logging
- filter combat alerts based on their sound id so they no longer show up as warnings
- keep first occurrence of an entry in the log when logging repetitions so both the first and last timestamp can be seen
- updated for High Isle

- added new api functions Logger:SetMinLevelOverride and Logger:SetLogTracesOverride to allow authors to temporarily enable debug logging for their addon (see description for more details)
- updated for Deadlands

- added additional information to startup logging
- updated for Blackwood

- fixed incorrect addon version (thanks esran!)

- log end of initial loading screen on info level so it shows correctly in the external log viewer when using the default configuration
- updated for Markarth

- added new function to dynamically change the sub tag of a Logger (see Logger:SetSubTag)
- added a way to append internal formatting errors at the end of the log output (see lib:ToggleFormattingErrors)
- modified Create function so it can be called both ways (lib.Create or lib:Create)
- updated for Greymoor

- reorganized code into multiple files
- disabled logging stack traces and debug log level by default during UI load
- added StartUpConfig.lua which should be used by authors to define settings used during UI load
- improved startup logging to include some additional information
- added new log level "verbose" which has to be whitelisted in StartUpConfig.lua. See API Reference for details when to use which log level.
- added new method Log() to logger which accepts a log level as first argument.
- deprecated lib.CALLBACK_* constants. Use lib.callback.* defined in callbacks.lua instead
- deprecated GetSessionStartTime. Use lib.SESSION_START_TIME instead
- deprecated GetUiLoadStartTime. Use lib.UI_LOAD_START_TIME instead

- updated for chat system changes in game version 5.3.5
- fixed incorrect arguments in fallback message logging
- added assertion to prevent creating a logger without a tag, which would cause trouble for DebugLogViewer

- added new APIs (see description for full details)
* settings functions
* getters for session and ui start time
* function to rebuild split log strings
* various constants, enums and variables
* callbacks for log modifications
- improved slash command settings menu
- reuse provided stack trace from Lua errors when possible
- update last logging time on identical log messages
- added chat debug output logging
- added ingame error alert logging
- added loading screens logging
- added IsLibrary flag

- prune log during session before it grows too big to load on next login
- store identical messages following after one another only once and start counting afterwards
- some minor code and performance improvements

- added a safeguard to ensure logging an error won't ever create more errors
- added more debug information to startup log (e.g. platform, ui, addon paths, ...)
- fixed LibDebugLogger("MyAddon") passing the wrong argument as tag
Archived Files (14)
File Name
04/17/23 04:51 PM
06/15/22 02:28 PM
06/10/22 01:01 PM
11/01/21 10:09 AM
06/01/21 11:38 AM
11/12/20 12:32 PM
11/12/20 10:37 AM
04/21/20 02:45 PM
04/10/20 11:24 AM
03/02/20 12:10 PM
06/01/19 08:23 AM
03/16/19 04:39 AM
03/04/19 12:10 PM
02/26/19 10:22 AM

Post A Reply Comment Options
Unread 03/16/19, 04:40 AM  
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1552
File comments: 1089
Uploads: 41
Thanks to everyone who sent in their files I was able to identify the problem. Turned out that it is caused by other addons that throw a large number of errors and fill up the LibDebugLogger saved variables until the game can no longer load it. I have updated LibDebugLogger so it keeps its log at a manageable size during the session instead of only removing surplus entries at login.
The two addons I have identified so far are BugCatcher and LUI Extended. I have contacted the author of LUI Extended and the error there should be fixed soon. BugCatcher seems to be abandoned and you should probably disable it, as it is throwing multiple errors per frame, which can have a severe impact on the game performance.
Report comment to moderator  
Reply With Quote
Unread 03/11/19, 03:45 PM  

Forum posts: 0
File comments: 22
Uploads: 0
Deleting the lua file from Saved Variables also worked for me. Thank you!

Before the delete, the DebugLogger was crashing me back to the login screen from any attempt at character load.
Report comment to moderator  
Reply With Quote
Unread 03/11/19, 02:52 PM  

Forum posts: 0
File comments: 12
Uploads: 0
Re: Re: Not working for me

Originally Posted by sirinsidiator
Have you tried to remove the LibDebugLogger.lua from your Saved Variables folder? Does it work then?
Otherwise I need more information. More specifically the operating system you are using and any errors or other unusual entries in the interface.log file in live/Logs.
Omg it worked!!!!!!! You are amazing. Thanks a million times for responding.
Report comment to moderator  
Reply With Quote
Unread 03/11/19, 01:25 PM  

Forum posts: 0
File comments: 4
Uploads: 0
hey there,
I had the same issue as written below but to delete the debuglogger.lua from saved variables works fine for me. thanks for that. appriciate your fast response to that question.
Report comment to moderator  
Reply With Quote
Unread 03/11/19, 01:10 PM  
sirinsidiator's Avatar
AddOn Author - Click to view AddOns

Forum posts: 1552
File comments: 1089
Uploads: 41
Re: Not working for me

Have you tried to remove the LibDebugLogger.lua from your Saved Variables folder? Does it work then?
Otherwise I need more information. More specifically the operating system you are using and any errors or other unusual entries in the interface.log file in live/Logs.
Report comment to moderator  
Reply With Quote
Unread 03/11/19, 01:05 PM  

Forum posts: 0
File comments: 12
Uploads: 0
Not working for me

Hiya. I posted on Awesome Guild Store's comment section a few days back...I finally isolated my issue to this library precisely, but I am unsure how to fix it. Every other lib works fine, as does AGS, but when I select this lib to load, it crashes back to log-in screen. Any ideas on how to fix this? I know most people have this add-on and its libraries working fine, so it's probably only on my end. Thanks!!
Report comment to moderator  
Reply With Quote
Unread 03/02/19, 02:26 PM  
Architecture's Avatar
AddOn Author - Click to view AddOns

Forum posts: 7
File comments: 79
Uploads: 8
nice job on this! Love the log stack trace feature too.
Report comment to moderator  
Reply With Quote
Post A Reply

Category Jump:

Support AddOn Development!

You have just downloaded by the author . If you like this AddOn why not consider supporting the author? This author has set up a donation account. Donations ensure that authors can continue to develop useful tools for everyone.