[tor-commits] [tor/master] state-contents.txt: try to document circ-build-timeout fields

[nickm at torproject.org]

commit 5ffd8bf2b8b0c051647179968218432ae5e5eb87
Author: Nick Mathewson <nickm at 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]...