debug api

Debug Mode API reference

Module

local Debug = LibStub("LibEQOLDebugMode-1.0")

Umbrella access (if present):

local Debug = LibEQOL and LibEQOL.DebugMode

Addon registration

RegisterAddon(addonKey, config)

Registers (or updates) one isolated addon tenant.

• addonKey (string, required)
• config (table, optional)

Returns: true on success, or nil, err.

Config schema:

{
  tier = "off" | "basic" | "deep", -- default: "off"
  persistence = {
    enabled = true|false, -- default: false
    savedRoot = table,    -- required when enabled=true
    path = { "A", "B" } or "A.B", -- required when enabled=true
  },
  limits = {
    maxEventsPerSession = number, -- default: 500
    maxSessions = number,         -- default: 10
    maxPayloadBytes = number,     -- default: 4096
    maxSpanDepth = number,        -- default: 32
  },
}

UnregisterAddon(addonKey)

Stops an active session (if any) and removes the addon tenant.

Returns: true or nil, err.

SetTier(addonKey, tier)

Updates tier (off, basic, deep).

Returns: normalized tier or nil, err.

GetTier(addonKey)

Returns current tier or nil if addon is not registered.

Session control

StartSession(addonKey, opts?)

Explicitly activates capture for one addon key.

• Fails if addon is not registered.
• Fails when tier is off.
• Fails when another session for that addon key is active.
• Validates persistence path when persistence is enabled.

opts:

{ tier = "off" | "basic" | "deep" } -- optional tier override for this session start

Returns: sessionId or nil, err.

StopSession(addonKey, reason?)

Stops active session, auto-closes remaining open spans (deep mode), stores session in ringbuffer, and flushes persistence.

Returns: sessionId (and optionally persistence error as second value).

IsSessionActive(addonKey)

Returns true/false.

GetActiveSessionId(addonKey)

Returns sessionId or nil.

Capture APIs

All capture APIs hard early-exit if there is no active session.

Trace(addonKey, eventName, payload?, parentId?)

Adds breadcrumb/trace event.

Returns: eventId or nil.

CaptureError(addonKey, where, err, payload?, parentId?)

Adds error event.

Returns: eventId or nil.

BeginSpan(addonKey, spanName, payload?, parentId?)

Deep-mode only. Opens a hierarchical span.

Returns: spanId or nil.

EndSpan(addonKey, spanId, status?, payload?)

Deep-mode only. Closes a span.

Returns: eventId of the closing event or nil.

Wrap(addonKey, where, fn, opts?)

Returns a wrapped function that captures thrown errors via xpcall.

opts:

{
  rethrow = true|false,  -- default: true
  span = true|false,     -- default: true (deep mode only)
  spanPayload = any,
  errorPayload = any,
  parentId = number,
}

Returns: wrappedFn or nil, err when fn is invalid.

Retrieval / export

GetTimeline(addonKey, opts?)

Returns a structured timeline table for one session.

opts:

{
  sessionId = number,    -- explicit session
  latestStored = true,   -- pick latest stored (ignore active)
}

Default: active session if available, otherwise latest stored session.

Returns: timelineTable or nil, err.

BuildReport(addonKey, opts?)

Builds a structured report plus a copy-ready text report.

Returns: reportTable, reportText or nil, nil, err.

ClearActiveSession(addonKey)

Drops in-memory active session without storing it.

Returns: true or nil, err.

ClearStoredSessions(addonKey)

Clears stored session history for the addon key and flushes persistence.

Returns: true or nil, err.