[tor-commits] [torspec/master] Attempt to clarify new CIRC_BW fields

[nickm at torproject.org]

commit 06cbab3eae78356c8c51d61c37bfdfe7518dbfbc
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue May 15 11:32:34 2018 -0700

    Attempt to clarify new CIRC_BW fields
    
    I didn't really follow the last description so trying one of my own...
    
      https://trac.torproject.org/projects/tor/ticket/26110
    
    Note that this description likely is *not* accurate. I didn't dig through tor's
    source to puzzle out what these fields are. Rather, this is a more grokable
    description of what I *think* the fields are. On the above ticket the Network
    team and I will work together on a description that's both easily understood
    and accurate.
---
 control-spec.txt | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index 72ceb15..d78b7ec 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -2945,15 +2945,13 @@
   BytesRead and BytesWritten are the number of bytes read and written
   on this circuit since the last CIRC_BW event.
 
-  DeliveredBytesRead and DeliveredBytesWritten are the total length of
-  all valid relay cell payloads read and written on this circuit since
-  the last CIRC_BW event. These fields are provided only in Tor
-  3.4.0-alpha and later.
+  Circuit data falls into two categories: delivered payloads and overhead.
+  DeliveredBytesRead and DeliveredBytesWritten are the total payloads
+  transmitted since the last CIRC_BW event, whereas OverheadBytesRead and
+  OverheadBytesWritten are the metadata size used for routing.
 
-  OverheadBytesRead and OverheadBytesWritten are the total length of
-  the unused overhead portion of valid relay cells read and written on
-  this circuit since the last CIRC_BW event. These fields are provided
-  only in Tor 0.3.4.0-alpha and later.
+  The sum of DeliveredBytesRead and OverheadBytesRead SHOULD match BytesRead,
+  and same for their written counterparts.
 
   The Time field is provided only in versions 0.3.2.1-alpha and later. It
   records when Tor created the bandwidth event.
@@ -2964,6 +2962,9 @@
 
   [First added in 0.2.5.2-alpha]
 
+  [DELIVERED_READ, OVERHEAD_READ, DELIVERED_WRITTEN, and OVERHEAD_WRITTEN was
+  added in Tor 0.3.4.0-alpha]
+
 4.1.23. Per-circuit cell stats
 
   The syntax is: