From 1111acee494ec3c0f3dccc19b368ddac52604635 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Tue, 28 Apr 2026 13:39:47 -0700
Subject: [PATCH] FUSE-Mount: document -fuse.congestionThreshold flag (#9258)

---
 FUSE-Mount.md | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/FUSE-Mount.md b/FUSE-Mount.md
index c7c910f..0073031 100644
--- a/FUSE-Mount.md
+++ b/FUSE-Mount.md
@@ -353,16 +353,16 @@ Notes:
 * `-cacheDirWrite` (if unset, falls back to `-cacheDir`, which defaults to `os.TempDir()`) is where the swap file lives. When upload stalls are possible it is strongly recommended to point this at a dedicated disk — not `/tmp` — and to set `-writeBufferSizeMB` below the available space on that disk.
 * The cap is a mount-global limit, not per-file. With many concurrently open writers it will serialize them rather than corrupt any of them.
 
-### Tuning kernel FUSE concurrency (`-fuse.maxBackground`)
+### Tuning kernel FUSE concurrency (`-fuse.maxBackground`, `-fuse.congestionThreshold`)
 
 The Linux kernel FUSE driver caps the number of asynchronous in-flight requests it will hand to a userspace filesystem at once. Two knobs control this, both exposed under `/sys/fs/fuse/connections/<id>/`:
 
 * `max_background` — hard cap on background (asynchronous) requests in flight.
-* `congestion_threshold` — when in-flight requests reach this value, the kernel marks the bdi as congested, throttling new submissions. Derived as `3/4 * max_background`.
+* `congestion_threshold` — when in-flight requests reach this value, the kernel marks the bdi as congested, throttling new submissions. Default is `3/4 * max_background`.
 
 Default `max_background` in `weed mount` is **128**, which is fine for most workloads. Heavy parallel-upload workloads (large `rclone`/`rsync` syncs, ML dataset ingest, many writer processes) can saturate that queue and become latency-bound on the FUSE channel itself rather than on volume servers.
 
-`-fuse.maxBackground=N` lets you raise the cap at mount time, so the value persists across reboots without a startup script that writes to `/sys/fs/fuse/connections/<id>/max_background`:
+`-fuse.maxBackground=N` and `-fuse.congestionThreshold=N` let you set both at mount time, so the values persist across reboots without a startup script that writes to `/sys/fs/fuse/connections/<id>/...`:
 
 ```bash
 weed mount \
@@ -370,17 +370,26 @@ weed mount \
   -fuse.maxBackground=2048
 ```
 
-With the example above, the kernel sets `max_background=2048` and `congestion_threshold=1536` (3/4 of 2048) on the new FUSE connection — equivalent to:
+With only `-fuse.maxBackground=2048`, the kernel sets `max_background=2048` and derives `congestion_threshold=1536` (3/4 of 2048) on the new FUSE connection — equivalent to:
 
 ```bash
 echo 2048 | sudo tee /sys/fs/fuse/connections/<id>/max_background
 echo 1536 | sudo tee /sys/fs/fuse/connections/<id>/congestion_threshold
 ```
 
+If you want a non-3/4 ratio (for example, more headroom before congestion kicks in), set both:
+
+```bash
+weed mount \
+  -filer=localhost:8888 -dir=/mnt/seaweedfs \
+  -fuse.maxBackground=2048 \
+  -fuse.congestionThreshold=1900
+```
+
 Notes:
-* The flag only changes a kernel queue-depth limit; it does not allocate memory in `weed mount` itself. Pair with `-concurrentWriters`/`-concurrentReaders` if the userspace side is also the bottleneck.
-* `congestion_threshold` is derived by the kernel-FUSE layer as `3/4 * max_background` and is not separately tunable from the command line. If you need a non-3/4 ratio, write `/sys/fs/fuse/connections/<id>/congestion_threshold` directly after mount.
-* Raising this value is cheap; raising it without measuring is rarely useful. Confirm queue saturation (e.g. via FUSE-channel latency or stalled-writer symptoms) before tuning.
+* These flags only change a kernel queue-depth limit; they do not allocate memory in `weed mount` itself. Pair with `-concurrentWriters`/`-concurrentReaders` if the userspace side is also the bottleneck.
+* `-fuse.congestionThreshold=0` (the default) tells the kernel-FUSE layer to use the conventional `3/4 * max_background`. The kernel silently clamps the value to `max_background` if it is set higher.
+* Raising these values is cheap; raising them without measuring is rarely useful. Confirm queue saturation (e.g. via FUSE-channel latency or stalled-writer symptoms) before tuning.
 
 ### Weed Mount Performance