Skip to content

docs(capture): NFS flush ceiling is metadata-RPC count, not fsync; add durability-vs-response-timing - #201

Merged
RhizoNymph merged 2 commits into
feat/integrationfrom
docs/capture-nfs-durability
Jun 24, 2026
Merged

docs(capture): NFS flush ceiling is metadata-RPC count, not fsync; add durability-vs-response-timing#201
RhizoNymph merged 2 commits into
feat/integrationfrom
docs/capture-nfs-durability

Conversation

@RhizoNymph

Copy link
Copy Markdown
Owner

Completes the filesystem-consumer docs piece from #174 (the only part not already merged via #195/#198/#200).

What changed

docs/features/capture_consumers.md:

  • New Durability vs. response timing subsection: the HTTP response fires at text-generation completion; capture files are written asynchronously and may report status: "pending". Clients should wait for the expected file set (layers × hooks), not a fixed sleep. Points at the capture_wait request flag for servers that want to block.
  • Reconciled the fsync table row and the new subsection with our own NFS measurements.

Why this differs from #174's wording

#174 attributed the per-small-file NFS ceiling to fsync being a synchronous COMMIT round-trip. Our filesystem investigation found the governing cost is metadata-RPC count (create/open/close/rename), not fsyncfsync/atomic_publish toggles are near-no-ops on a sync NFS export, while the packed/sharded layouts (which collapse metadata RPCs per request) are the real lever. Measured ~90 small files/s (~30 MB/s at ~350 KB/file) vs. ~93% of raw disk bound for large contiguous writes. The docs now state that cause.

@RhizoNymph
RhizoNymph merged commit dbebbe2 into feat/integration Jun 24, 2026
@RhizoNymph
RhizoNymph deleted the docs/capture-nfs-durability branch June 24, 2026 21:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant