commit 5ffd8bf2b8b0c051647179968218432ae5e5eb87 Author: Nick Mathewson nickm@torproject.org Date: Tue Sep 22 14:44:30 2020 -0400

state-contents.txt: try to document circ-build-timeout fields

This should also get feedback from @mikeperry.

Closes #40136 --- doc/state-contents.txt | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/doc/state-contents.txt b/doc/state-contents.txt index 58c77bc292..7c3ba99659 100644 --- a/doc/state-contents.txt +++ b/doc/state-contents.txt @@ -91,9 +91,24 @@ Recognized fields are: TotalBuildTimes CircuitBuildAbandonedCount CircuitBuildTimeBin - BuildTimeHistorgram

- XXXX writeme. + These fields are used by the Circuit Build Timeout code, which + tries to learn what times are reasonable for circuit construction, + so that it can reject circuits that take too long to build. + + CircuitBuildTimeBin is a count of circuits that were build + successfully in some timeframe. This entry can repeat; each of + these represents some bar on a histogram. The first integer is a + number of milliseconds; it tells the position of the center of the + histogram bin on the time axis. The second number is a count of + circuits in that bin. + + CircuitBuildTimeAbandonedCount is a count of circuits that we + simply gave up on building because they were taking far too long. + + TotalBuildTimes is the number of circuit build times that we + observed in order to build the above measurements fields. If it + reaches a cap, then older measurements get thrown away.

Guard [key=value] [key=value]...