mangohud-logger-steamos/README.md

mangohud-logger

One-touch toggle for MangoHud CSV logging on Linux gaming-launcher systems (SteamOS Game Mode, DeckShift, super-alt-S, plain gamescope-session-plus, or any setup that already uses MangoHud).

Run the script — it switches logging on if it's off, off if it's on. CSV samples land in ~/Downloads/mango-logs/. That's the entire interface.

Why this exists

Getting MangoHud to actually write logs from a Steam-via-gamescope game turns out to be a multi-step setup, and every step has a non-obvious gotcha. Worse, the right setup differs depending on which gamescope session manager your distro ships. This script detects that and handles it so you don't have to.

What it changes

The script writes marker-tagged files (so it can clean them up on disable, and won't trample anything you wrote by hand):

1. ~/.config/MangoHud/MangoHud.conf — appends a marker-bracketed block with output_folder, autostart_log=1, log_duration=0 (= until you quit), log_interval=100, toggle_logging=Shift_L+F2, and a no_display=0 override. (Also serves as the on/off state marker.)

2. ~/.config/environment.d/95-mangohud-logger.conf — contains:

   • MANGOHUD=1 so the Vulkan loader auto-injects MangoHud into every game.
   • MANGOHUD_CONFIG=<inline copy of the logging keys>. This is the important one for SteamOS Game Mode — see Game Mode below.

   Requires a logout/login to take effect (systemd-user only reads environment.d/*.conf at session start).

3. ~/.config/gamescope-session-plus/sessions.d/steam — only written on the gamescope-session-plus session flavor (see flavor detection below). A user-level override that unsets the system's MANGOHUD_CONFIGFILE and turns off STEAM_USE_MANGOAPP. Not written on stock SteamOS.

When you toggle it off, the script removes everything it wrote.

Session-flavor detection

Game Mode is launched differently on different distros, and the fix differs too. On enable, the script detects which one you have (detect_gs_flavor):

Flavor	Detected by	What the script does
plus	/usr/share/gamescope-session-plus/sessions.d/steam exists	Writes the sessions.d/steam override (file #3).
steamos	/usr/lib/steamos/gamescope-session exists	Skips file #3; relies on MANGOHUD_CONFIG (file #2). See below.
none	neither	Desktop-only; MANGOHUD=1 is enough for Vulkan games.

SteamOS Game Mode

Stock SteamOS (e.g. 3.x "holo") launches Game Mode via /usr/lib/steamos/gamescope-session, not gamescope-session-plus. That session script unconditionally does:

export STEAM_USE_MANGOAPP=1
export MANGOHUD_CONFIGFILE="$tmpdir/mangohud.config"   # written with just "no_display"

and it sources no user override file — so the old sessions.d/steam trick does nothing here, and you can't override STEAM_USE_MANGOAPP from environment.d (the session exports it afterwards).

How logging actually works here: the on-screen overlay in Game Mode is mangoapp (a compositor overlay), and mangoapp is MangoHud — it can write CSV logs itself. Steam launches mangoapp with your systemd user environment, so it inherits the MANGOHUD_CONFIG from file #2. MANGOHUD_CONFIG takes precedence over the session's no_display MANGOHUD_CONFIGFILE, so mangoapp picks up autostart_log/output_folder and logs every game — no per-game launch options needed.

Notes:

• Logs are named mangoapp_<timestamp>.csv (the logger is mangoapp, not the in-game layer), so a file spans a Game Mode session rather than one-per-game.
• You must fully restart into Game Mode once after enabling (log out/in or reboot) so mangoapp inherits MANGOHUD_CONFIG. If you enable while already in Game Mode, that session won't have it and nothing logs.
• Verified on SteamOS 3.9 with MangoHud 0.8.3-rc1: a Proton game (DREDGE) in Game Mode produced a 1039-row mangoapp_*.csv of real fps/frametime data.

Per-game fallback (if you don't want to restart the session, or want the in-game Vulkan layer instead of mangoapp): set this in a game's Steam → Properties → Launch Options:

MANGOHUD_CONFIGFILE=$HOME/.config/MangoHud/MangoHud.conf mangohud %command%

Gotchas it works around

• no_display blocks autostart_log. MangoHud's autostart_log rides on the render hook that no_display disables, so the log never starts. The script's block ends with no_display=0. Tradeoff: while logging is on, the HUD is visible during games.

• The system session forces a no_display config file. Both session flavors export MANGOHUD_CONFIGFILE pointing at a temp file containing only no_display, which would suppress your real config. On plus the script unsets that var; on steamos the MANGOHUD_CONFIG env var overrides it.

• Steam uses mangoapp instead of the in-game Vulkan layer in Game Mode. STEAM_USE_MANGOAPP=1. On steamos you can't turn this off globally — so the script leans into it and lets mangoapp do the logging (see above). On plus the override sets STEAM_USE_MANGOAPP=0 to use the in-game layer.

• log_duration=0 means "log forever". Empirically 0 = log until you quit or hit the toggle key.

• MANGOHUD=1 only injects the Vulkan layer. OpenGL-only games still need mangohud %command% in Steam launch options or an LD_PRELOAD wrapper.

Install

Requires mangohud (and lib32-mangohud for 32-bit games). On Arch / SteamOS:

sudo pacman -S mangohud lib32-mangohud

Then:

git clone https://github.com/28allday/mangohud-logger-steamos.git
cd mangohud-logger-steamos
chmod +x mangohud-logger.sh
./mangohud-logger.sh

Or copy the script anywhere on $PATH:

install -Dm755 mangohud-logger.sh ~/.local/bin/mangohud-logger
mangohud-logger

Usage

./mangohud-logger.sh

No flags, no subcommands. First run enables; second run disables. After the first enable, log out and back in (Game Mode users: fully restart into Game Mode) so the env vars become effective. You only need to do that once.

In-game keys (set by the script's MangoHud block):

Key	Action
Shift+F2	Toggle logging on/off mid-game
Your existing toggle_hud key	Hide the HUD overlay (logging keeps running)

CSV files appear in ~/Downloads/mango-logs/. Drop them into https://flightlessmango.com/ for graphs, or open in a spreadsheet.

Compatibility

• SteamOS Game Mode (/usr/lib/steamos/gamescope-session) — logs via mangoapp; see Game Mode.
• DeckShift (28allday/DeckShift) — gamescope-session-plus based.
• super-alt-S (28allday/super-alt-S-cachy-deckmode) — KDE-Plasma gaming mode on CachyOS.
• Plain gamescope-session-plus on any Arch-based distro.
• Steam without gamescope — works too; the gamescope override becomes a no-op.
• Non-systemd distros — the environment.d file won't be read; set MANGOHUD=1 (and MANGOHUD_CONFIG) via your distro's env-var mechanism.

Honours XDG

Log folder is $XDG_DOWNLOAD_DIR/mango-logs (resolved via xdg-user-dir), config dir is $XDG_CONFIG_HOME — works on non-English locales.

License

MIT