Skip to content

Commit 91d9fec

Browse files
kriszypclaude
andcommitted
fix(docs): sync maxTransactionQueueTime bypass note and remove stale duplicate wording
Verified against resources/Table.ts:2218,4407 (checkOverloaded guarded by !context?.source) and the 503 log text in DatabaseTransaction.ts:403: deletes and canonical-source writes (replication, caching sources) bypass the queue-time check entirely. Note that in storage-tuning.md, and sync configuration/options.md's duplicate one-line description (previously "Max write queue time before 503", which re-introduced the queue-length framing this branch corrects elsewhere) to point at the same section instead of drifting. Also tighten the maxDepth field description: the high-water mark resets on emit, which is activity-gated, not a fixed sampling interval. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
1 parent a90548d commit 91d9fec

3 files changed

Lines changed: 6 additions & 6 deletions

File tree

reference/analytics/overview.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -204,10 +204,10 @@ once a commit settles, so a genuinely wedged commit contributes no sample at all
204204
remains outstanding. Harper also logs once per stuck commit when the 503 check itself fires, which is
205205
the authoritative signal for that specific failure.
206206

207-
| Field | Unit | Description |
208-
| ---------- | ----- | ------------------------------------------------- |
209-
| `depth` | count | Instantaneous depth sampled at emit time |
210-
| `maxDepth` | count | High-water mark observed over the sampling period |
207+
| Field | Unit | Description |
208+
| ---------- | ----- | ------------------------------------------------------- |
209+
| `depth` | count | Instantaneous depth sampled at emit time |
210+
| `maxDepth` | count | High-water mark since this thread's last emitted sample |
211211

212212
- **`write-transaction-queue-depth`** counts write commits handed to the storage engine whose commit
213213
promises have not yet settled — how many commits this thread is juggling concurrently. This is

reference/configuration/options.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ storage:
253253
- `compression` — LZ4 record compression; _Default_: `true` (enabled by default since v4.3.0). Sub-options: `dictionary`, `threshold`
254254
- `compactOnStart` — Compact all non-system databases on startup; _Default_: `false` (Added in: v4.3.0)
255255
- `compactOnStartKeepBackup` — Retain compaction backups; _Default_: `false`
256-
- `maxTransactionQueueTime` — Max write queue time before 503; _Default_: `45s`
256+
- `maxTransactionQueueTime` — Max time a single write commit may stay unsettled before Harper starts rejecting writes with 503; see [Storage Tuning](../database/storage-tuning.md#storagemaxtransactionqueuetime); _Default_: `45s`
257257
- `noReadAhead` — Advise OS against read-ahead; _Default_: `false`
258258
- `prefetchWrites` — Prefetch before write transactions; _Default_: `true`
259259
- `path` — Database files directory; _Default_: `<rootPath>/database`

reference/database/storage-tuning.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Type: `string` (duration)
3737

3838
Default: `45s`
3939

40-
The maximum time a single write commit may remain unsettled before Harper starts rejecting new writes on that thread with HTTP 503. This is a per-commit duration check, not a queue-length threshold — it acts as backpressure when downstream disk I/O cannot keep up with incoming writes.
40+
The maximum time a single write commit may remain unsettled before Harper starts rejecting new application-originated writes on that thread with HTTP 503. This is a per-commit duration check, not a queue-length threshold — it acts as backpressure when downstream disk I/O cannot keep up with incoming writes. Deletes and writes applied from a canonical source (e.g. replication or a caching source) bypass this check.
4141

4242
Lower this in latency-sensitive systems where it is better to shed load early than to let request queues grow. Raise it when occasional disk-write bursts are expected and the application can tolerate longer commit latency.
4343

0 commit comments

Comments
 (0)