[tor-commits] [tor/master] Try to document pathbias fields in state file.

[nickm at torproject.org]

commit 371cd7ac4f538f6f70ae9c35680e78d39f9e01dd
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Sep 22 14:35:11 2020 -0400

    Try to document pathbias fields in state file.
    
    This will require feedback from @mikeperry, since these are a bit
    subtle and I've likely mangled some of these.
---
 doc/state-contents.txt | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/state-contents.txt b/doc/state-contents.txt
index 9fe41f67a1..58c77bc292 100644
--- a/doc/state-contents.txt
+++ b/doc/state-contents.txt
@@ -155,8 +155,39 @@ Recognized fields are:
          pb_circ_attempts
          pb_successful_circuits_closed
          pb_collapsed_circuits
+         pb_unusable_circuits
          pb_timeouts
 
+              Used by the pathbias subsystem to keep a record of the
+              behavior of circuits built through this guard, in hopes of
+              detecting guards try to that interfere with traffic.
+
+              All of these fields are floating-point integers which
+              represent a count of circuits that have been trated in
+              various ways.  These counts decay with time.
+
+              "use_attempts" is a count of the circuits that we've built
+              and tried to use for traffic.
+
+              "successful_circuits_closed" is a count of circuits that
+              have closed "naturally" without timeout or error.
+
+              "use_successes" is a count of circuits that we've sent
+              traffic on, and which closed "naturally" without timeout
+              or error.
+
+              "circ_attempts" is a count of circuits we've tried to
+              build through this guard.
+
+              "collapsed_circuits" is a count of circuits that failed
+              after having been built, but before sending traffic.
+
+              "unusable_circuits" is a count of circuits that we
+              launched as path-bias probes but which failed to build,
+              or which encountered questionable errors.
+
+              "timeouts" is a count of circuits that encountered a
+              timeout while we were building them.
 
 Obsolete fields include: