debug getting started

Getting started (Debug Mode)

Use this module when your addon needs explicit debug sessions and timeline-based bug reports.

1) Load the module

local Debug = LibStub("LibEQOLDebugMode-1.0")

Embed include (optional module):

<Include file="libs/LibEQOL/LibEQOLDebugMode.xml" />

2) Register your addon key

MyAddonDebugDB = MyAddonDebugDB or {}

Debug:RegisterAddon("MyAddon", {
    tier = "deep", -- default is "off"
    persistence = {
        enabled = true,
        savedRoot = MyAddonDebugDB,
        path = { "Debug", "Sessions" }, -- or "Debug.Sessions"
    },
    limits = {
        maxEventsPerSession = 500,
        maxSessions = 10,
        maxPayloadBytes = 4096,
        maxSpanDepth = 32,
    },
})

3) Start and stop explicitly

local sessionId, err = Debug:StartSession("MyAddon")
if not sessionId then
    print("Debug start failed:", err)
    return
end

-- ...capture calls...

Debug:StopSession("MyAddon", "manual-stop")

Without an active session, capture calls are hard no-ops.

4) Capture timeline data

Debug:Trace("MyAddon", "OpenConfig", { tab = "General" })

local spanId = Debug:BeginSpan("MyAddon", "ApplyProfile", { profile = "Raid" })
Debug:Trace("MyAddon", "ValidateData")
Debug:CaptureError("MyAddon", "LoadProfile", "invalid profile id")
Debug:EndSpan("MyAddon", spanId, "error")

5) Wrap risky code

local wrapped = Debug:Wrap("MyAddon", "ImportProfile", function(profileString)
    return ImportProfile(profileString)
end, {
    rethrow = false,
})

local ok, importErr = wrapped("...")
if not ok and importErr then
    print("Import failed:", importErr)
end

6) Export report

local report, text, exportErr = Debug:BuildReport("MyAddon")
if not report then
    print("Export failed:", exportErr)
    return
end

print(text) -- copy/paste into bug report

See full API details on debug-api.