docs: add worker-pool and data-plane tuning how-to#107
Closed
jmcorgan wants to merge 1 commit into
Closed
Conversation
Document the data-plane performance-tuning environment variables introduced with the off-task encrypt/decrypt worker pools and per-peer connected UDP. None of these knobs were documented outside source doc-comments. The new guide pairs with tune-udp-buffers.md: the two cover adjacent concerns (UDP socket buffers vs. per-stage worker queues) and operators tuning one will want to find the other. Covers worker-pool sizing, per-peer connected UDP, send-path backpressure, the per-stage perf profiler, and the macOS-specific send knobs, each with its real default, what it does, and the observability mode that would prompt tuning it. Includes the massive-mesh FIPS_CONNECTED_UDP=0 escape hatch note (one drain thread per established peer) and a see-also linking the UDP receive buffer ceiling to the decrypt worker queue capacity. Adds the guide to the how-to index.
Owner
Author
|
Closing this draft unmerged for now. It has been open without review interest, and the worker-pool tuning knobs it documents are stable, so the how-to can wait. The content is preserved and can be reopened later if we decide to ship operator-facing data-plane tuning docs. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/how-to/tune-worker-pools.md, an operator how-to for thedata-plane performance-tuning environment variables introduced with the
off-task encrypt/decrypt worker pools and per-peer connected UDP (#91).
None of these knobs were documented outside source doc-comments. The
guide pairs with the existing
tune-udp-buffers.md: the two coveradjacent concerns (UDP socket buffers vs. per-stage worker queues), and
an operator tuning one will want to find the other. Also adds the guide
to the how-to index.
Closes #101.
What it documents
All of the startup-time runtime knobs, grouped:
FIPS_ENCRYPT_WORKERS,FIPS_DECRYPT_WORKERSFIPS_CONNECTED_UDP,FIPS_MACOS_CONNECTED_UDPFIPS_SEND_BACKPRESSURE_SLEEP_AFTER/_SLEEP_MICROS/_DROP_AFTERFIPS_PERF,FIPS_PIPELINE_TRACE,FIPS_PERF_INTERVAL_SECSFIPS_MACOS_ORDERED_SENDER,_WORKER_STRIDE,_WORKER_BATCH,_SEND_FLOW_IDLE_MS,_SEND_PACE_MBPS,_SEND_PACE_BURST_BYTES,_NET_SERVICE_TYPEEach knob lists its real default (read from source, including the
macOS/Linux split on the backpressure gates), what it does, and the
observability mode that would prompt tuning it. Includes the
massive-mesh
FIPS_CONNECTED_UDP=0escape-hatch note (one drain threadper established peer) and a see-also linking the UDP receive buffer
ceiling to the decrypt worker queue capacity.
Review ask
@mmalmi this documents your #91 work, so I would value an accuracy pass
on the prose, especially:
does nothing for a single flow)
DROP_AFTERis the ceiling checked firstcollapse on Wi-Fi)
FIPS_MACOS_NET_SERVICE_TYPEOne correction worth flagging: the doc uses 32768 as the decrypt worker
channel capacity (
decrypt_worker.rs), not the 1024 that #101'sdescription listed. 1024 is the encrypt channel capacity; the two
differ.
Notes
Documentation only, no code changes. Defaults and behavior were read
from source at this branch's base.