feat(profiling): HOS_PROFILE=1, one switch for every profiling tool, into a folder of its own, and scripts/profile_report.py to read it #1279
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1279
Loading…
Reference in a new issue
No description provided.
Delete branch "HumanBean/Longshot:feat/profile-mode"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: feat · Risk: low · Tested on: Linux, RTX 3090 (NVIDIA 620.70.06) · Needs: a Windows run of
HOS_PROFILE=1Why
Finding what to optimize next, or what a stutter was, took several switches set by hand, files in several places, and samplers started and stopped at the right moment. Most of those files had no common clock, so a stutter could not be matched to what the threads were doing. This PR makes it one switch,
HOS_PROFILE=1, and adds one command that reads the result into a report and a profiler's timeline. It replacesHOS_RECORD_STUTTERS(#1218).What changed
One switch records a whole run into a folder of its own, and one script reads it: a markdown report of where the time goes and what each stutter was, a Perfetto timeline of every thread, and speedscope flame graphs.
HOS_PROFILE=1(host/profiling.c; allowed inlongshot_env.txt). It writeslogs/profile-<date>-<time>/, a new folder each run:all.txt: every game and renderer thread's stack every 2 ms, from the start. Packed (HOS_SAMPLE_PACKED): each distinct stack is written once, about a tenth of the plain format's size.frames.csv: the frame trace, with a new last columnat_ns, the present on the host's clock (host->now_ns).presents.csv,cpu.csv(process CPU and memory every second) andevents.txt(each long virtual-core wait, with its time).process.json(switches; paths outside the game folder are left out) andlongshot_options.ini.HOS_FPS_LOG,RX_VK_PASS_TIMING=1andRX_VK_SLOW_LOG=50.host/posix/prof.c,host/mkw_glue.c) take their thread list again every 5 s in file mode too, as the slow-frame ring already did. They write throughhos_sample_write.HOS_PROFILE=<seconds>(the busiest threads' log alone) is nowHOS_PROFILE_EVERY. An oldHOS_PROFILE=5turns the whole mode on and says so in the log.HOS_RECORD_STUTTERSonly logs a note namingHOS_PROFILE=1.scripts/profile_report.py <folder>writesreport.md:scripts/profile_trace.py(also run by the report) writestrace.json.gzfor Perfetto (a flame chart per thread over time, frames, stutters, virtual-core waits, counters) andspeedscope.json.scripts/samples.pyreads both sample formats.crit.py,hotlist.py,vkprof.py,chain.pyandcpu_report.pyuse it.docs/development.mdhas a new "The profiling mode" section and rows for the switches;docs/performance-report.mdgives players the one line; README, CONTRIBUTING.md and cpu-profile.md are updated.tests/test_profiling_mode.py(new) compiles the packed writer, reads it back, and checks the report and the trace on a made-up folder. It also has source checks.test_frame_trace_waits.pycoversat_ns;test_slow_frames.pyandtest_vcore_escape.pyare updated.Measurements
Nothing to measure as a gain: a diagnostic, off by default.
Flags and settings
Adds the profiling mode and renames the busiest-threads log; both are off by default.
HOS_PROFILE=<seconds>: the busiest threads' log=1: the profiling mode, off by defaultlogs/profile-<date>-<time>/HOS_PROFILE_EVERYHOS_PROFILE=1HOS_PROFILE=<n>did)HOS_SAMPLE_PACKEDHOS_PROFILE=1HOS_SAMPLE_ALL's fileHOS_RECORD_STUTTERSHOS_PROFILE=1HOS_PROFILE_DIRlongshot_env.txt)frames.csvgoes into the folderTesting
Tested: Linux, RTX 3090, NVIDIA 620.70.06, CachyOS kernel 7.3.3. A pack over the base
ac778751, run withscripts/memtour.py --repo-save kokiri-start --dests 13 --dwell 10 --env HOS_PROFILE=1(headless).mkw_vk_*and the rest.profile_report.pyread 96 s of play (6,246 frames, 65 fps; 28 frames of 50 ms or more, around the Zora's Domain load) in 29 s.trace.json.gz(14 MB) opened in Perfetto with the thread, frame, wait and counter tracks.Not tested:
python -I -B tests/run_all.py: not run on this PC (no test suites run on it); left to CI.profiling.c(GetProcessTimes,K32GetProcessMemoryInfo,_putenv) haven't been compiled.Must be tested:
HOS_PROFILE=1inlongshot_env.txt, expecting alogs/profile-...folder whoseall.txtnames the game's and renderer's threads, and thatscripts/profile_report.pyreads (with--mapsto the build's maps).Risks
What could break:
HOS_PROFILE=<seconds>now get the whole mode, which costs frame rate. The log says so.at_ns.Turning it off: leave
HOS_PROFILEunset (the default).Compatibility:
longshot_frames.csvgains a column at its end.HOS_SAMPLE_ALL's plain format is unchanged unlessHOS_SAMPLE_PACKEDis set. No cache, save or options file changes.Issues
Prior work: #1218 (the slow-frame recorder, the frame trace's main-thread columns, the vcore wait log), which this builds on; #928 (the Breakdown);
HOS_SAMPLE_ALLandscripts/cpu_report.py.Checklist
Everyone
type(scope): description) of the status line's type.main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named). Not run on this PC (no test suites run on it); left to CI.third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.tests/that reads changed source updated in this PR, not weakened.🤖 Generated with Claude Code
Tested in game: Linux, RTX 3090, NVIDIA 620.70.06, CachyOS: HOS_PROFILE=1 with scripts/memtour.py (kokiri-start, teleport to Zora's Domain, 10 s dwell, headless). The profile folder held every file, with every game and renderer thread sampled; profile_report.py read 96 s of play (6,246 frames, 65 fps, 28 frames over 50 ms around the load) and its trace.json.gz opened in Perfetto.
Possibly related, for context:
Phishinabowl referenced this pull request2026-11-17 00:35:40 +00:00
Tested on Windows, the "Must be tested" item: Windows 11, RX 6700 XT, AMD 26.10.1, Ryzen 5 5600, main @
8e9cfc3a(this PR's merge commit, the same commit as nightly-397). The build wasscripts/dev_build.py base, so the Windows-only parts ofhost/profiling.ccompile with llvm-mingw. The run waslongshot_ctl.py launch --headless --profile test --repo-save kokiri-start --env HOS_PROFILE=1, about 11 minutes. The control client never got the game past the menu here, so it is the menu at ~226 fps plus the start: no teleports. That is a harness issue on my side, not this PR.Works on Windows:
logs/profile-<date>-<time>/holds every file:all.txt(packed),frames.csvwithat_ns,presents.csv,cpu.csv,events.txt(24 vcore waits),process.json(paths outside the game folder left out) andlongshot_options.ini. The log names the folder.all.txtnames the game's and the renderer's threads (sead::MainThread,mkw_vk_replay,mkw_vk_recorder,Presentation_Thread,ARes_Loading_*and the rest; 60+ of them). It starts with 1 thread and picks up the rest as they appear (the 5 s retake).profile_report.pyreads it with the build'slongshot.map/longshot_vk.mapfound by default, and writesreport.md,trace.json.gzandspeedscope.json. The GPU pass timing block comes through too.Found on the way (not blockers; I'll take the first two as follow-ups unless someone has them):
main_cpu_msis per-tick on Windows (from #1218, read by this report).GetThreadTimesadvances in scheduler ticks, so in 154,200 frames the column took only 0, 15.6 and 31.2 ms (139,570 / 14,613 / 16 frames). Per frame, main CPU + blocked comes out larger than the frame: steady frames average 1.48 + 3.36 ms in 4.39 ms frames, and the stutters show 358.9 ms of CPU in 164 ms frames. The report's "main thread on the CPU / blocked / off the CPU" split can't be trusted on Windows until that is a real per-frame time (e.g.QueryThreadCycleTime, scaled by a measured TSC rate).report.mdtable issues:prof: threads innames (mkw_vk replay) against the samples' names (mkw_vk_replay, spaces made_by both samplers), so each such thread gets two rows: one with the CPU %, one with the samples. That likely happens on Linux too._ZN5mkwvk12_GLOBAL__N_14waitEyy), andprof.demangleonly knows MSVC's, so the C++ frames stay mangled.all.txtis 494 MB for ~11 min (about 45 MB a minute with every thread at 2 ms, packed), and the report took 278 s and wrote a 76 MB trace. It might be worth a line indocs/performance-report.mdasking players for a few minutes around the problem rather than a whole session.longshot_ctl.pythe game's log goes to the run folder, notlogs/longshot_log.txt, so the report finds no log. The Threads CPU % and GPU sections come out empty unless the log is copied in asgame.log. Players' runs aren't affected.