docs: document performance profiles and tuning options

commit: 8db9a6a902371598568c61c37c3862a82e90808c
author: brice · 9mo ago · 2025-12-28 17:55 UTC
committer: brice · 9mo ago · 2025-12-29 17:28 UTC
parent: 74a67e9
signature: unsigned

1 file · +90 -0

M docs/CONFIG.md +90 -0


@@ -491,6 +491,96 @@ dumber config migrate
491	491		dumber config migrate --yes
492	492		```
493	493
	494	+	## Performance Profiles
	495	+
	496	+	Performance profiles provide preset configurations for WebKitGTK tuning. These settings affect Skia rendering threads, memory pressure handling, and WebView pool behavior.
	497	+
	498	+	> Note: Performance settings are applied at browser startup. Changes require a restart to take effect.
	499	+
	500	+	\| Key \| Type \| Default \| Valid Values \| Description \|
	501	+	\|-----\|------\|---------\|--------------\|-------------\|
	502	+	\| `performance.profile` \| string \| `"default"` \| `default`, `lite`, `max`, `custom` \| Performance profile selection \|
	503	+
	504	+	### Profiles
	505	+
	506	+	\| Profile \| Description \| Use Case \|
	507	+	\|---------\|-------------\|----------\|
	508	+	\| `default` \| No tuning, uses WebKit defaults \| Normal browsing, most users \|
	509	+	\| `lite` \| Reduced resource usage \| Low-RAM systems (< 4GB), battery saving \|
	510	+	\| `max` \| Maximum responsiveness \| Heavy pages (GitHub PRs, complex SPAs), high-end systems \|
	511	+	\| `custom` \| Manual control over all settings \| Advanced users who want fine-grained control \|
	512	+
	513	+	### Profile Settings Matrix
	514	+
	515	+	\| Setting \| default \| lite \| max \|
	516	+	\|---------\|---------\|------\|-----\|
	517	+	\| Skia CPU threads \| unset \| 2 \| `NumCPU()/2` (min 4) \|
	518	+	\| Skia GPU threads \| unset \| unset \| 2 \|
	519	+	\| Web process memory (MB) \| unset \| 512 \| 2048 \|
	520	+	\| Network process memory (MB) \| unset \| 256 \| 512 \|
	521	+	\| Conservative threshold \| unset \| 0.25 \| 0.5 \|
	522	+	\| Strict threshold \| unset \| 0.4 \| 0.7 \|
	523	+	\| Kill threshold \| unset \| 0.8 \| unset (never) \|
	524	+	\| WebView pool prewarm \| 4 \| 2 \| 8 \|
	525	+
	526	+	Example:
	527	+	```toml
	528	+	[performance]
	529	+	profile = "default" # Most users - no tuning needed
	530	+
	531	+	# For low-RAM systems:
	532	+	# profile = "lite"
	533	+
	534	+	# For heavy pages (GitHub PRs, complex web apps):
	535	+	# profile = "max"
	536	+
	537	+	# For manual control:
	538	+	# profile = "custom"
	539	+	```
	540	+
	541	+	### Custom Profile Settings
	542	+
	543	+	When `profile = "custom"`, you can configure individual tuning options:
	544	+
	545	+	\| Key \| Type \| Default \| Description \|
	546	+	\|-----\|------\|---------\|-------------\|
	547	+	\| `performance.skia_cpu_painting_threads` \| int \| `0` \| Skia CPU rendering threads (0=unset) \|
	548	+	\| `performance.skia_gpu_painting_threads` \| int \| `-1` \| Skia GPU rendering threads (-1=unset, 0=disable) \|
	549	+	\| `performance.skia_enable_cpu_rendering` \| bool \| `false` \| Force CPU rendering \|
	550	+	\| `performance.web_process_memory_limit_mb` \| int \| `0` \| Web process memory limit in MB (0=unset) \|
	551	+	\| `performance.web_process_memory_poll_interval_sec` \| float \| `0` \| Memory check interval (0=WebKit default: 30s) \|
	552	+	\| `performance.web_process_memory_conservative_threshold` \| float \| `0` \| Conservative cleanup threshold (0=unset) \|
	553	+	\| `performance.web_process_memory_strict_threshold` \| float \| `0` \| Strict cleanup threshold (0=unset) \|
	554	+	\| `performance.web_process_memory_kill_threshold` \| float \| `-1` \| Process kill threshold (-1=unset, 0=never kill) \|
	555	+	\| `performance.network_process_memory_limit_mb` \| int \| `0` \| Network process memory limit in MB \|
	556	+	\| `performance.network_process_memory_poll_interval_sec` \| float \| `0` \| Network memory check interval \|
	557	+	\| `performance.network_process_memory_conservative_threshold` \| float \| `0` \| Network conservative threshold \|
	558	+	\| `performance.network_process_memory_strict_threshold` \| float \| `0` \| Network strict threshold \|
	559	+	\| `performance.network_process_memory_kill_threshold` \| float \| `-1` \| Network process kill threshold \|
	560	+	\| `performance.webview_pool_prewarm_count` \| int \| `4` \| WebViews to pre-create at startup \|
	561	+	\| `performance.zoom_cache_size` \| int \| `256` \| Domain zoom levels to cache \|
	562	+
	563	+	Custom profile example:
	564	+	```toml
	565	+	[performance]
	566	+	profile = "custom"
	567	+
	568	+	# Skia threading - tune for your CPU
	569	+	skia_cpu_painting_threads = 4
	570	+	skia_gpu_painting_threads = 2
	571	+
	572	+	# Web process memory pressure
	573	+	web_process_memory_limit_mb = 1024
	574	+	web_process_memory_conservative_threshold = 0.4
	575	+	web_process_memory_strict_threshold = 0.6
	576	+	web_process_memory_kill_threshold = -1 # Never kill
	577	+
	578	+	# WebView pool
	579	+	webview_pool_prewarm_count = 6
	580	+	```
	581	+
	582	+	> Important: Individual tuning fields are ignored unless `profile = "custom"`. Setting individual fields with any other profile will produce a validation warning.
	583	+
494	584		## Environment Variables
495	585
496	586		All config values can be overridden via environment variables with the prefix `DUMBER_`:


@@ -491,6 +491,96 @@ dumber config migrate
491	dumber config migrate --yes	491		dumber config migrate --yes
492	```	492		```
493		493
		494	+	## Performance Profiles
		495	+
		496	+	Performance profiles provide preset configurations for WebKitGTK tuning. These settings affect Skia rendering threads, memory pressure handling, and WebView pool behavior.
		497	+
		498	+	> Note: Performance settings are applied at browser startup. Changes require a restart to take effect.
		499	+
		500	+	\| Key \| Type \| Default \| Valid Values \| Description \|
		501	+	\|-----\|------\|---------\|--------------\|-------------\|
		502	+	\| `performance.profile` \| string \| `"default"` \| `default`, `lite`, `max`, `custom` \| Performance profile selection \|
		503	+
		504	+	### Profiles
		505	+
		506	+	\| Profile \| Description \| Use Case \|
		507	+	\|---------\|-------------\|----------\|
		508	+	\| `default` \| No tuning, uses WebKit defaults \| Normal browsing, most users \|
		509	+	\| `lite` \| Reduced resource usage \| Low-RAM systems (< 4GB), battery saving \|
		510	+	\| `max` \| Maximum responsiveness \| Heavy pages (GitHub PRs, complex SPAs), high-end systems \|
		511	+	\| `custom` \| Manual control over all settings \| Advanced users who want fine-grained control \|
		512	+
		513	+	### Profile Settings Matrix
		514	+
		515	+	\| Setting \| default \| lite \| max \|
		516	+	\|---------\|---------\|------\|-----\|
		517	+	\| Skia CPU threads \| unset \| 2 \| `NumCPU()/2` (min 4) \|
		518	+	\| Skia GPU threads \| unset \| unset \| 2 \|
		519	+	\| Web process memory (MB) \| unset \| 512 \| 2048 \|
		520	+	\| Network process memory (MB) \| unset \| 256 \| 512 \|
		521	+	\| Conservative threshold \| unset \| 0.25 \| 0.5 \|
		522	+	\| Strict threshold \| unset \| 0.4 \| 0.7 \|
		523	+	\| Kill threshold \| unset \| 0.8 \| unset (never) \|
		524	+	\| WebView pool prewarm \| 4 \| 2 \| 8 \|
		525	+
		526	+	Example:
		527	+	```toml
		528	+	[performance]
		529	+	profile = "default" # Most users - no tuning needed
		530	+
		531	+	# For low-RAM systems:
		532	+	# profile = "lite"
		533	+
		534	+	# For heavy pages (GitHub PRs, complex web apps):
		535	+	# profile = "max"
		536	+
		537	+	# For manual control:
		538	+	# profile = "custom"
		539	+	```
		540	+
		541	+	### Custom Profile Settings
		542	+
		543	+	When `profile = "custom"`, you can configure individual tuning options:
		544	+
		545	+	\| Key \| Type \| Default \| Description \|
		546	+	\|-----\|------\|---------\|-------------\|
		547	+	\| `performance.skia_cpu_painting_threads` \| int \| `0` \| Skia CPU rendering threads (0=unset) \|
		548	+	\| `performance.skia_gpu_painting_threads` \| int \| `-1` \| Skia GPU rendering threads (-1=unset, 0=disable) \|
		549	+	\| `performance.skia_enable_cpu_rendering` \| bool \| `false` \| Force CPU rendering \|
		550	+	\| `performance.web_process_memory_limit_mb` \| int \| `0` \| Web process memory limit in MB (0=unset) \|
		551	+	\| `performance.web_process_memory_poll_interval_sec` \| float \| `0` \| Memory check interval (0=WebKit default: 30s) \|
		552	+	\| `performance.web_process_memory_conservative_threshold` \| float \| `0` \| Conservative cleanup threshold (0=unset) \|
		553	+	\| `performance.web_process_memory_strict_threshold` \| float \| `0` \| Strict cleanup threshold (0=unset) \|
		554	+	\| `performance.web_process_memory_kill_threshold` \| float \| `-1` \| Process kill threshold (-1=unset, 0=never kill) \|
		555	+	\| `performance.network_process_memory_limit_mb` \| int \| `0` \| Network process memory limit in MB \|
		556	+	\| `performance.network_process_memory_poll_interval_sec` \| float \| `0` \| Network memory check interval \|
		557	+	\| `performance.network_process_memory_conservative_threshold` \| float \| `0` \| Network conservative threshold \|
		558	+	\| `performance.network_process_memory_strict_threshold` \| float \| `0` \| Network strict threshold \|
		559	+	\| `performance.network_process_memory_kill_threshold` \| float \| `-1` \| Network process kill threshold \|
		560	+	\| `performance.webview_pool_prewarm_count` \| int \| `4` \| WebViews to pre-create at startup \|
		561	+	\| `performance.zoom_cache_size` \| int \| `256` \| Domain zoom levels to cache \|
		562	+
		563	+	Custom profile example:
		564	+	```toml
		565	+	[performance]
		566	+	profile = "custom"
		567	+
		568	+	# Skia threading - tune for your CPU
		569	+	skia_cpu_painting_threads = 4
		570	+	skia_gpu_painting_threads = 2
		571	+
		572	+	# Web process memory pressure
		573	+	web_process_memory_limit_mb = 1024
		574	+	web_process_memory_conservative_threshold = 0.4
		575	+	web_process_memory_strict_threshold = 0.6
		576	+	web_process_memory_kill_threshold = -1 # Never kill
		577	+
		578	+	# WebView pool
		579	+	webview_pool_prewarm_count = 6
		580	+	```
		581	+
		582	+	> Important: Individual tuning fields are ignored unless `profile = "custom"`. Setting individual fields with any other profile will produce a validation warning.
		583	+
494	## Environment Variables	584		## Environment Variables
495		585
496	All config values can be overridden via environment variables with the prefix `DUMBER_`:	586		All config values can be overridden via environment variables with the prefix `DUMBER_`: