Configuration

It works out of the box, but you can tweak its behavior with these environment variables, process arguments, or a configuration file.
The defaults are sensible, so you only need these if you want to change something.

Variable	Default	What it does
CRASHCAPTURE_TIMEOUT	10	How many seconds the server can be unresponsive before it's treated as frozen. 0 turns freeze detection off.
CRASHCAPTURE_HANG_KILL	30	After a freeze report, force-close the process this many seconds later. 0 means never.
CRASHCAPTURE_LOOPBREAK	1	On a freeze, if the stalled thread is in Lua, arms a Lua debug hook on every realm that raises an error to break out of a stuck loop.
CRASHCAPTURE_PHYS_RESUME	1	Linux only, when a fatal fault happens inside the physics tick (PhysFrame, under Host_RunFrame), pause physics and resume the game thread as if the physics call returned.
CRASHCAPTURE_PHYS_HOOK	1	Linux only, prevents runaway physics hangs at the source instead of just reporting them.
CRASHCAPTURE_PHYS_HOOK_MS	250	per-tick budget, in milliseconds, before the hook above steps in. Clamped to a minimum of 20.
CRASHCAPTURE_PHYS_RECOVER	1	Linux only, after a physics stall, freeze the offending objects so the tick can finish instead of stalling again.
CRASHCAPTURE_PHYS_PIN	0	Linux only, also pin the offending objects in place (motion disabled) rather than only reporting them.
CRASHCAPTURE_PHYS_RESOLVE_DELAY	3	Linux only, frames to wait after a physics recovery before firing the crashcapture.physresolve hook, so physics has settled.
CRASHCAPTURE_PHYS_DEFER_EPS_US	0	Linux only, defer retained-mindist events whose next refire lands within this many microseconds of the current drain position. Experimental.
CRASHCAPTURE_REPORT_DEBOUNCE	15	Minimum seconds between repeat reports for the same recurring condition. 0 disables the debounce.
CRASHCAPTURE_HANG_MAP	1	When a hang is detected, burst-probe the stuck thread a few times and include a Hang map report section showing the PC sites it kept landing on.
CRASHCAPTURE_HANG_MAP_SAMPLES	16	How many probes the hang map takes. Clamped to 1..64.
CRASHCAPTURE_HANG_MAP_INTERVAL_MS	10	Milliseconds between hang-map probes. Clamped to 1..5000.
CRASHCAPTURE_ENGINE_ERROR	1	Capture engine-side fatal errors (Sys_Error and friends) instead of letting them exit silently.
CRASHCAPTURE_FRAME_PROFILE	1	Collect per-frame timing metrics (what crashcapture.frametime() returns). On Linux this also times the server physics tick (PhysFrame).
CRASHCAPTURE_PROFILE	0	Arm the Lua call profiler. See Lua Profiler.
CRASHCAPTURE_PROFILE_WINDOW	300	Seconds before the profiler retires the current window and starts a fresh one, so it can be left armed indefinitely, 0 never rotates.
CRASHCAPTURE_DEBUG	0	Verbose internal tracing. Noisy, for troubleshooting the plugin itself.
CRASHCAPTURE_MEMAPI	0	Expose the mem.* API to Lua. Unsafe, see the warning below.
CRASHCAPTURE_PATCHES	1	Master switch for the compiled-in engine patches. See Patcher.
CRASHCAPTURE_CLIENT_LUA	0	Client preload/sideload only, installs the crashcapture Lua API and the heartbeat timer into the client realm.
CRASHCAPTURE_WINDOW_WATCHDOG	1	On Windows clients with no other heartbeat, detect a frozen game by watching its window.
CRASHCAPTURE_LUA_HEARTBEAT	1	Use a lightweight in-game timer as the freeze heartbeat.
CRASHCAPTURE_MANUAL_DUMP	1	Let an external process force a report on demand. See Manual Dump.
CRASHCAPTURE_FIRSTCHANCE	auto	Windows: also catch certain early/internal errors. Auto-managed; usually leave alone.
CRASHCAPTURE_CONSOLE	0	Print the full report to the console too. Off by default, only a short notice and the file path are printed.
CRASHCAPTURE_SYMBOLS	1	Add function names and source lines to reports when debug info is available. No effect when it isn't.
CRASHCAPTURE_DISABLE	0	Set to 1 to make the plugin do nothing at all. Handy for ruling it out when troubleshooting.
CRASHCAPTURE_DIR	crashes	Folder to write reports into (relative to the GMod root).
CRASHCAPTURE_MAX_AGE_DAYS	14	At startup, delete reports in the crash folder older than this many days, so they don't pile up. 0 keeps them forever.
CRASHCAPTURE_SCRIPT	(none)	Path to a Lua script run in a fresh, isolated state on each crash for live memory diagnostics. See Crash Script Diagnostics. Off when unset.

Warning

We recommend not having CRASHCAPTURE_MEMAPI enabled, as this exposes the same API layer of mem.* to one or multiple lua_State's.
Proceed with caution when this is enabled, as this is inherently unsafe.

Configuration file

Hosts that cannot set environment variables or process arguments can drop a crashcapture.cfg into the crash folder instead.
Settings are resolved in this order:

1. Environment variables, if set.
2. Process arguments (-CRASHCAPTURE_TIMEOUT 30, and so on).
3. crashcapture.cfg in the crash folder.
4. Runtime crashcapture.set() from Lua, which always wins once a realm is up, see Lua API.

Each line is a key = value pair using the setting names above, with or without the CRASHCAPTURE_ prefix (case-insensitive).
Lines starting with # or // are comments, inline comments must be preceded by whitespace.
A repeated key keeps the last value.

# crashes/crashcapture.cfg
timeout = 30
debug = 1 # verify signatures are not drifting
CRASHCAPTURE_DIR = my reports
phys_hook_ms = 500

The file is read from the crash folder resolved by environment variables and process arguments (default crashes/).
A dir line in the file redirects where reports are written, but the file itself is always read from that resolved folder.
All settings work here, including the launch-only ones (dir, script, memapi, phys_hook, console) and disable = 1.

Runtime settings from Lua

Once a realm is up, most settings can be read and changed from Lua through the crashcapture table.
See Lua API for the full list of keys and the launch-only exceptions.