bandwidth-file: Add header KeyValues to monitor relays

Part of #29754.

1 files changed, 127 insertions, 0 deletions

diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt
index d06488f..de2b7ae 100644
--- a/bandwidth-file-spec.txt
+++ b/bandwidth-file-spec.txt
@@ -302,6 +302,133 @@
 
       This Line was added in version 1.3.0 of this specification.
 
+    "recent_consensus_count=" Int NL
+
+      [Zero or one time.].
+
+      The number of the different consensuses seen in the last data_period
+      days. (data_period is 5 by default.)
+
+      Assuming that Tor clients fetch a consensus every 1-2 hours,
+      and that the data_period is 5 days, the Value of this Key SHOULD be
+      between:
+          data_period * 24 / 2 =  60
+          data_period * 24     = 120
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_priority_list_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of times that a list with a subset of relays prioritized
+      to be measured has been created in the last data_period days.
+      (data_period is 5 by default.)
+
+      In 2019, with 7000 relays in the network, the Value of this Key SHOULD be
+      approximately:
+          data_period * 24 / 1.5 = 80
+      Being 1.5 the approximate number of hours it takes to measure a
+      priority list of 7000 * 0.05 (350) relays, when the fraction of relays
+      in a priority list is the 5% (0.05).
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_priority_relay_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of relays that has been in in the list of relays prioritized
+      to be measured in the last data_period days. (data_period is 5 by
+      default.)
+
+      In 2019, with 7000 relays in the network, the Value of this Key SHOULD be
+      approximately:
+          80 * (7000 * 0.05) = 28000
+      Being 0.05 (5%) the fraction of relays in a priority list and 80
+      the approximate number of priority lists (see
+      "recent_priority_list_count").
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_measurement_attempt_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of times that any relay has been queued to be measured
+      in the last data_period days. (data_period is 5 by default.)
+
+      In 2019, with 7000 relays in the network, the Value of this Key SHOULD be
+      approximately the same as "recent_priority_relay_count",
+      assuming that there is one attempt to measure a relay for each relay that
+      has been prioritized unless there are system, network or implementation
+      issues.
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_measurement_failure_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of times that the scanner attempted to measure a relay in
+      the last data_period days (5 by default), but the relay has not been
+      measured because of system, network or implementation issues.
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_measurements_excluded_error_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of relays that have no successful measurements in the last
+      data_period days (5 by default).
+
+      (See the note in section 1.4, version 1.4.0, about excluded relays.)
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_measurements_excluded_near_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of relays that have some successful measurements in the last
+      data_period days (5 by default), but all those measurements were
+      performed in a period of time that was too short (by default 1 day).
+
+      (See the note in section 1.4, version 1.4.0, about excluded relays.)
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_measurements_excluded_old_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of relays that have some successful measurements, but all
+      those measurements are too old (more than 5 days, by default).
+
+      Excludes relays that are already counted in
+      recent_measurements_excluded_near_count.
+
+      (See the note in section 1.4, version 1.4.0, about excluded relays.)
+
+      This Line was added in version 1.4.0 of this specification.
+
+    "recent_measurements_excluded_few_count=" Int NL
+
+      [Zero or one time.]
+
+      The number of relays that don't have enough recent successful
+      measurements. (Fewer than 2 measurements in the last 5 days, by
+      default).
+
+      Excludes relays that are already counted in
+      recent_measurements_excluded_near_count and
+      recent_measurements_excluded_old_count.
+
+      (See the note in section 1.4, version 1.4.0, about excluded relays.)
+
+      This Line was added in version 1.4.0 of this specification.
+
     KeyValue NL
 
       [Zero or more times.]