!!PerfLog - performance diagnostics for WoW 1.12 (vanilla / Turtle WoW)
========================================================================

INSTALL
Source: https://octowow.st/git/Hapto/PerfLog
Copy the files into Interface\AddOns\!!PerfLog. The folder must be named !!PerfLog or WoW won't load it.

HOW TO USE
1. Play normally (raid, battleground, city...). The addon records everything by itself.
2. Drop a marker whenever you feel a slowdown:  /perflog mark lag on pull
3. After the session (no need to quit the game), open
   Interface\AddOns\!!PerfLog\Viewer\PerfLogViewer.html in your web browser
   and drop the file  <WoW folder>\CustomData\PerfLog_<Character>_<Realm>_<date>_<client>.log
   onto it. There is one file per client session (login or /reload); you can drop
   several files and switch between them with the list at the top right.

REQUIREMENTS
- nampower (WriteCustomFile) to write the log file continuously.
  Without nampower the log goes to the SavedVariables instead
  (WTF\Account\<account>\SavedVariables\!!PerfLog.lua, written on logout or /reload),
  and the viewer can read that file too.
- Optional: SuperWoW, ClassicAPI and WeirdUtils versions are recorded when present.
- Optional: ducielperf 0.3.0+ gives exact Lua allocations per addon (see below).

COMMANDS (/perflog or /plog)
  /perflog               status (file, memory, number of hitches)
  /perflog mark <text>   add a marker to the log
  /perflog top           live top 10 of the most expensive addons / handlers
  /perflog flush         write the log to disk now
  /perflog off | on      stop / resume logging
  /perflog profile off   turn per-addon profiling off (lighter; keeps FPS/GC/hitches)
  /perflog alloc on|off  exact per-addon allocation tracking (ducielperf; on by default)
  /perflog fs on|off     read ducielperf's engine frame counters (on by default;
                         "off" only stops PerfLog reading them, the DLL keeps counting)
  /perflog mem           Lua memory held by each addon, top 10 in chat (ClassicAPI; out of combat)
  /perflog hitch 60      hitch threshold in ms (default 60)
  /perflog window 30     per-addon measurement interval in seconds (default 30)
  /perflog gc            force a garbage collection and measure how long it takes

WHAT IS MEASURED
- FPS, worst frame of each second, frames > 33/50/100 ms, latency, Lua memory, GC.
- Every hitch (frame longer than the threshold) with its likely cause: the guilty
  Lua handler, a garbage collection, or a non-Lua cause (rendering, disk, network).
- For each addon and each OnEvent/OnUpdate/OnShow/OnHide handler: exclusive CPU
  time, number of calls, Lua memory allocated, garbage collections triggered.
- How often each event fires and how many handlers it wakes up.
- With ducielperf: exact Lua memory allocated by each addon (every allocation,
  including those made inside game API calls and by handlers PerfLog does not
  wrap), and for each hitch the addons that allocated the most in the second
  before it. PerfLog switches the DLL's tracking on at load if it is not on yet.
- With ducielperf 0.4.0+: time spent each second in disk/MPQ reads, decompression,
  model and texture loading and server packets, and the same counters for the
  slow frame of each hitch, so "Not Lua" hitches get a cause. When the DLL's
  freeze watchdog writes a report (Logs\ducielperf_freezes.log), a marker is
  added to the timeline. PerfLog never switches the watchdog or the counting off.
- With ducielperf 0.4.1+: exact Lua garbage collection figures (number of
  collections, time spent collecting, bytes freed, bytes allocated) for each
  second and each hitch, instead of guessing collections from drops of
  gcinfo(). Without the DLL the old estimate is used.
- With ducielperf 0.5.0+: long strings (table.concat, string.format, gsub...)
  are built without garbage. PerfLog notes it in the header (strbuf) and logs
  how many strings over 512 bytes were built per window. Allocation and GC
  figures from before 0.5.0 are not comparable with newer ones.
- Markers: combat, zone changes, loading screens, group size.
- Boss fights (with BigWigs): pull, kill and wipe of each boss. The viewer shows
  one row per fight (FPS, hitches, GC, garbage and CPU by addon).
- Lua memory held by each addon at each loading screen (with ClassicAPI): every
  garbage collection walks all of it, so the biggest holders make every
  collection longer.
- Header: loaded addons, graphics and nampower CVars, mod versions.
- Game window in background: WoW throttles itself to ~4 FPS when it is not the
  active window. These throttled frames are recognised (3+ frames of 150 ms or
  more in a row, all about the same length, with almost no Lua time), are not
  logged as hitches, and the viewer leaves those periods out of its figures
  (shown as grey bands on the timeline). Logs from older versions are
  cleaned up the same way by the viewer.

NOTES
- The log is appended to disk every 10 seconds with WriteCustomFile.
- Profiling adds a small overhead (shown in the viewer as "PerfLog overhead").
- Delete old logs from CustomData from time to time (roughly 5-15 MB per hour).
- To turn it off completely, untick "PerfLog" in the addon list.
