[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
Re: [tor-dev] New documentation for Tor Metrics website
Karsten Loesing:
> Dear list,
Dear Karsten!
> writing documentation is hard work. I'm sure you already knew that, but
> let me re-assure you that I now believe it, too. At least until I
> forget it again and carelessly start documenting something else that
> looks tiny and friendly and trivial to document.
Thank you for spending time on this.
> Anyway, I spent the last day (felt like half a week) on rewriting the
> relevant text for the Tor Metrics website, and I wrote a short glossary
> of terms I didn't want to explain over and over.
>
> Would people on this list mind reviewing my text and suggesting
> improvements?
I had a look through and I didn't make any drastic changes, just picked
a few small nits. I attach a patch file for your reading pleasure. Let
me know if you disagree with anything or my changes have made things
even less clear.
Two comments:
1. "Statistics include subsets of relays or bridges by...country code
(only relays and only until February 2013)..."
Do you mean here "from the beginning of time until Feb '13" or "from
present day back as far as Feb '13"? I guess it would be clear from
context, but I understood the former; if the latter is meant then maybe
"as far back as" instead of "until".
2. You might include a definition of "consensus", since although it is a
technical term, it is not intuitive and comes up a few times in the rest
of the text. I haven't put it in the document in order to preserve the
line count but maybe it could go like this, if you wanted it:
<a name="consensus"></a><p><b><a href="#consensus">consensus:</a></b> a
single document compiled and voted on by the <a
href="#directory-authority">directory authorities</a> once per hour,
ensuring that all <a href="#client">clients</a> have the same
information about the <a href="#relay">relays</a> that make up the Tor
network.
with a link to the same entry where "consensus" appears elsewhere.
That's it.
> Thanks in advance, much appreciated! In fact, I'm pretty sure that all
> future visitors of Tor Metrics will appreciate your efforts.
Thanks for writing the documentation!
14c14
< <a name="advertised-bandwidth"></a><p><b><a href="#advertised-bandwidth">advertised bandwidth:</a></b> traffic volume in both incoming and outgoing direction that a <a href="#relay">relay</a> is willing to sustain, as configured by the operator, and that the relay reports as being capable to handle, as observed from recent data transfers.
---
> <a name="advertised-bandwidth"></a><p><b><a href="#advertised-bandwidth">advertised bandwidth:</a></b> the volume of traffic, both incoming and outgoing, that a <a href="#relay">relay</a> is willing to sustain, as configured by the operator and observed from recent data transfers. This value is self-reported and may not correspond to observations by the <a href="#directory-authority">directory authorities</a>.
18c18
< <a name="bandwidth-history"></a><p><b><a href="#bandwidth-history">bandwidth history:</a></b> traffic volume in incoming and/or outgoing direction that a <a href="#relay">relay</a> reports to have handled on behalf of <a href="#client">clients</a>.
---
> <a name="bandwidth-history"></a><p><b><a href="#bandwidth-history">bandwidth history:</a></b> the volume of incoming and/or outgoing traffic that a <a href="#relay">relay</a> claims to have handled on behalf of <a href="#client">clients</a>. This value is self-reported and may not correspond to observations by the <a href="#directory-authority">directory authorities</a>.
21c21
< <a name="bridge"></a><p><b><a href="#bridge">bridge:</a></b> non-publicly listed <a href="#relay">relay</a> that provides access for blocked <a href="#client">clients</a>, often in combination with <a href="#pluggable-transport">pluggable transports</a>, and that registers itself at the <a href="#bridge-authority">bridge authority</a>.
---
> <a name="bridge"></a><p><b><a href="#bridge">bridge:</a></b> a <a href="#relay">relay</a> whose existence is non-public and which can therefore provide access for blocked <a href="#client">clients</a>, often in combination with <a href="#pluggable-transport">pluggable transports</a>. Bridges usually register themselves with the <a href="#bridge-authority">bridge authority</a>.
23c23
< <a name="bridge-authority"></a><p><b><a href="#bridge-authority">bridge authority:</a></b> special-purpose <a href="#relay">relay</a> that maintains a list of bridges as input for external bridge distribution mechanisms (e.g., <a href="https://bridges.torproject.org/";>BridgeDB</a>).</p>
---
> <a name="bridge-authority"></a><p><b><a href="#bridge-authority">bridge authority:</a></b> a special-purpose <a href="#relay">relay</a> that maintains a list of bridges as input for external bridge distribution mechanisms (e.g., <a href="https://bridges.torproject.org/";>BridgeDB</a>).</p>
25c25
< <a name="circuit"></a><p><b><a href="#circuit">circuit:</a></b> path through the Tor network built by <a href="#client">clients</a> consisting of at most one <a href="#bridge">bridge</a> and at least one <a href="#relay">relay</a>.</p>
---
> <a name="circuit"></a><p><b><a href="#circuit">circuit:</a></b> a path through the Tor network built by <a href="#client">clients</a> consisting of at most one <a href="#bridge">bridge</a> and at least one <a href="#relay">relay</a>.</p>
27c27
< <a name="client"></a><p><b><a href="#client">client:</a></b> node in the Tor network running on behalf of typically one user to route application connections over a series of <a href="#relay">relays</a>.</p>
---
> <a name="client"></a><p><b><a href="#client">client:</a></b> a node in the Tor network, typically running on behalf of one user, that routes application connections over a series of <a href="#relay">relays</a>.</p>
29c29
< <a name="consensus-weight"></a><p><b><a href="#consensus-weight">consensus weight:</a></b> value assigned to a <a href="#relay">relay</a> that is based on bandwidth observed by the relay and bandwidth measured by the <a href="#directory-authority">directory authorities</a>, included in the hourly published consensus document, and used by <a href="#client">clients</a> to select relays for their <a href="#circuit">circuits</a>.
---
> <a name="consensus-weight"></a><p><b><a href="#consensus-weight">consensus weight:</a></b> a value assigned to a <a href="#relay">relay</a> that is measured by the <a href="#directory-authority">directory authorities</a>, included in the hourly published consensus document, and used by <a href="#client">clients</a> to select relays for their <a href="#circuit">circuits</a>.
31c31
< <a name="directory-authority"></a><p><b><a href="#directory-authority">directory authority:</a></b> special-purpose <a href="#relay">relay</a> that maintains a list of currently running relays and periodically publishes a consensus document together with the other directory authorities.</p>
---
> <a name="directory-authority"></a><p><b><a href="#directory-authority">directory authority:</a></b> a special-purpose <a href="#relay">relay</a> that maintains a list of currently-running relays and periodically publishes a consensus document together with the other directory authorities.</p>
33c33
< <a name="directory-mirror"></a><p><b><a href="#directory-mirror">directory mirror:</a></b> <a href="#relay">relay</a> that provides a recent copy of directory information to clients to reduce load on <a href="#directory-authority">directory authorities</a>.</p>
---
> <a name="directory-mirror"></a><p><b><a href="#directory-mirror">directory mirror:</a></b> a <a href="#relay">relay</a> that provides a recent copy of directory information to clients, in order to reduce the load on <a href="#directory-authority">directory authorities</a>.</p>
35c35
< <a name="hidden-service"></a><p><b><a href="#hidden-service">hidden service:</a></b> location-hidden service that is only accessible via the Tor network.</p>
---
> <a name="hidden-service"></a><p><b><a href="#hidden-service">hidden service:</a></b> a location-hidden service (for example, a website or instant-messaging server) that is only accessible via the Tor network.</p>
37c37
< <a name="pluggable-transport"></a><p><b><a href="#pluggable-transport">pluggable transport:</a></b> alternative transport protocol provided by <a href="#bridge">bridges</a> and used by <a href="#client">clients</a> to circumvent transport-level blockings.</p>
---
> <a name="pluggable-transport"></a><p><b><a href="#pluggable-transport">pluggable transport:</a></b> an alternative transport protocol provided by <a href="#bridge">bridges</a> and used by <a href="#client">clients</a> to circumvent transport-level blockings (for example, by ISPs or governments).</p>
39c39
< <a name="relay"></a><p><b><a href="#relay">relay:</a></b> publicly listed node in the Tor network that forwards traffic on behalf of <a href="#client">clients</a> and that registers itself at the <a href="#directory-authority">directory authorities</a>.
---
> <a name="relay"></a><p><b><a href="#relay">relay:</a></b> a publicly-listed node in the Tor network that forwards traffic on behalf of <a href="#client">clients</a>, and that registers itself with the <a href="#directory-authority">directory authorities</a>.
41c41
< <a name="relay-flag"></a><p><b><a href="#relay-flag">relay flag:</a></b> special (dis-)qualification of <a href="#relay">relays</a> for circuit positions (e.g., "Guard", "Exit", "BadExit"), circuit properties (e.g., "Fast", "Stable"), or roles (e.g., "Authority", "HSDir"), as assigned by the <a href="#directory-authority">directory authorities</a> and further defined in the <a href="https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt";>directory protocol specification</a>.</p>
---
> <a name="relay-flag"></a><p><b><a href="#relay-flag">relay flag:</a></b> a special (dis-)qualification of <a href="#relay">relays</a> for circuit positions (e.g., "Guard", "Exit", "BadExit"), circuit properties (e.g., "Fast", "Stable"), or roles (e.g., "Authority", "HSDir"), as assigned by the <a href="#directory-authority">directory authorities</a> and further defined in the <a href="https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt";>directory protocol specification</a>.</p>
64,65c64,65
< <p>The following graphs shows the number of running <a href="#relay">relays</a> that got certain <a href="#relay-flag">flags</a> assigned by the <a href="#directory-authority">directory authorities</a>.
< These flags indicate that a relay should be prefered for either guard ("Guard") or exit position ("Exit"), that a relay is suitable for high-bandwidth ("Fast") or long-lived circuits ("Stable"), or that a relay is considered a hidden service directory ("HSDir").</p>
---
> <p>The following graphs shows the number of running <a href="#relay">relays</a> that have had certain <a href="#relay-flag">flags</a> assigned by the <a href="#directory-authority">directory authorities</a>.
> These flags indicate that a relay should be preferred for either guard ("Guard") or exit positions ("Exit"), that a relay is suitable for high-bandwidth ("Fast") or long-lived circuits ("Stable"), or that a relay is considered a hidden service directory ("HSDir").</p>
73c73
< More details on when these versions have been declared stable or unstable can be found on the <a href="https://www.torproject.org/download/download.html.en";>download page</a> and in the <a href="https://gitweb.torproject.org/tor.git/blob/HEAD:/ChangeLog";>changes file</a>.</p>
---
> More details on when these versions were declared stable or unstable can be found on the <a href="https://www.torproject.org/download/download.html";>download page</a> and in the <a href="https://gitweb.torproject.org/tor.git/blob/HEAD:/ChangeLog";>changes file</a>.</p>
94,95c94,95
< Statistics include subsets of relays or bridges by <a href="glossary#relay-flag">relay flag</a> (only relays), country code (only relays and only until February 2013), tor software version (only relays), operating system (only relays), and whether or not being run in the EC2 cloud (only bridges).
< The data file contains daily averages (means) of relay and bridge numbers.</p>
---
> Statistics include subsets of relays or bridges by <a href="glossary#relay-flag">relay flag</a> (relays only), country code (relays only, and only until February 2013), tor software version (relays only), operating system (relays only), and by whether or not they are running in the EC2 cloud (bridges only).
> The data file contains daily (mean) averages of relay and bridge numbers.</p>
101c101
< <p>The following graph shows total <a href="#advertised-bandwidth">advertised</a> and <a href="#bandwidth-history">consumed bandwidth</a> of all <a href="#relay">relays</a> in the network.</p>
---
> <p>The following graph shows the total <a href="#advertised-bandwidth">advertised</a> and <a href="#bandwidth-history">consumed bandwidth</a> of all <a href="#relay">relays</a> in the network.</p>
107c107
< <p>The following graph shows <a href="#bandwidth-history">consumed bandwidth</a> of relays, subdivided into four distinct subsets by assigned "Exit" and/or "Guard" <a href="#relay-flag">flags</a>.</p>
---
> <p>The following graph shows the <a href="#bandwidth-history">consumed bandwidth</a> reported by relays, subdivided into four distinct subsets by assigned "Exit" and/or "Guard" <a href="#relay-flag">flags</a>.</p>
114c114
< These sets are not distinct, because a relay that has both the "Exit" and "Guard" flag assigned will be included in both sets.</p>
---
> These sets are not distinct, because a relay that has both the "Exit" and "Guard" flags assigned will be included in both sets.</p>
120,121c120,121
< <p>The following graph shows the portion of <a href="#bandwidth-history">consumed bandwidth</a> that <a href="#directory-authority">directory authorities</a> and <a href="#directory-mirror">mirrors</a> spent on answering directory requests.
< Not all directories report these statistics, so that the graph shows an estimation of total consumed bandwidth as it would be observed if all directories reported these statistics.</p>
---
> <p>The following graph shows the portion of <a href="#bandwidth-history">consumed bandwidth</a> that <a href="#relay">relays</a> have spent on answering directory requests.
> Not all relays report these statistics, so the graph shows an estimation of total consumed bandwidth as it would be observed if all relays reported these statistics.</p>
128c128
< Statistics on advertised bandwidth include any kind of traffic handled by a relay, whereas statistics on consumed bandwidth are available for all traffic together and specifically for serving directory data.
---
> Statistics on advertised bandwidth include any kind of traffic handled by a relay, whereas statistics on consumed bandwidth are available either for all traffic combined, or specifically for directory traffic.
130c130
< The data file contains daily averages (means) of bandwidth numbers.</p>
---
> The data file contains daily (mean) averages of bandwidth numbers.</p>
134c134
< <p>The following graph shows the distribution of <a href="glossary#advertised-bandwidth">advertised bandwidth</a> of relays in the network.
---
> <p>The following graph shows the distribution of the <a href="glossary#advertised-bandwidth">advertised bandwidth</a> of relays in the network.
142c142
< <p>The following graph shows the <a href="#advertised-bandwidth">advertised bandwidth</a> of the n-th fastest relays in the network.</p>
---
> <p>The following graph shows the <a href="#advertised-bandwidth">advertised bandwidth</a> of the n-th fastest relays in the network - please configure the value of n below the graph to obtain the statistics you need.</p>
151c151
< The data file contains daily averages (medians) of percentiles and n-th largest values.</p>
---
> The data file contains daily (median) averages of percentiles and n-th largest values.</p>
158c158
< Fast relays with at least 100 Mbit/s bandwidth capacity that have high probability of being selected for circuits are represented by an onion, smaller relays are shown as a simple dot, and the slowest relays which are almost never selected for circuits are omitted entirely.
---
> Fast relays with at least 100 Mbit/s bandwidth capacity, and which therefore have a high probability of being selected for circuits, are represented by an onion; smaller relays are shown as a simple dot; and the slowest relays, which are almost never selected for circuits, are omitted entirely.
168c168
< <p>The following graph shows the estimated number of directly connecting <a href="#client">clients</a>, that is, excluding clients connecting via <a href="#bridge">bridges</a>.
---
> <p>The following graph shows the estimated number of directly-connecting <a href="#client">clients</a>; that is, it excludes clients connecting via <a href="#bridge">bridges</a>.
171c171
< Further, it's possible to display indications of censorship events as obtained from an anomaly-based censorship-detection system (for more details, see this <a href="https://research.torproject.org/techreports/detector-2011-09-09.pdf";>technical report</a>).</p>
---
> Furthermore, it is possible to display indications of censorship events as obtained from an anomaly-based censorship-detection system (for more details, see this <a href="https://research.torproject.org/techreports/detector-2011-09-09.pdf";>technical report</a>).</p>
177c177
< <p>The following table shows the top-10 countries by estimated number of directly connecting <a href="#client">clients</a>.
---
> <p>The following table shows the top-10 countries by estimated number of directly-connecting <a href="#client">clients</a>.
183c183
< <p>The following table shows the top-10 countries by possible censorship events as obtained from an anomaly-based censorship-detection system (for more details, see this <a href="https://research.torproject.org/techreports/detector-2011-09-09.pdf";>technical report</a>).</p>
---
> <p>The following table shows the top-10 countries by possible censorship events, as obtained from an anomaly-based censorship-detection system (for more details, see this <a href="https://research.torproject.org/techreports/detector-2011-09-09.pdf";>technical report</a>).</p>
226c226
< There are statistics available by country (directly connecting clients and clients connecting via bridges), by transport protocol (only clients connecting via bridges), and by IP version (only clients connecting via bridges).
---
> There are statistics available by country (for both directly-connecting clients and clients connecting via bridges), by transport protocol (only for clients connecting via bridges), and by IP version (only for clients connecting via bridges).
228c228
< Statistics further include predicted client numbers from past observations which can be used to detect censorship events.</p>
---
> Statistics also include predicted client numbers from past observations, which can be used to detect censorship events.</p>
234,235c234,235
< <p>The following graph shows the overall performance of downloading static files of different sizes over Tor.
< The graph shows the range of measurements from first to third quartile and highlights the median.
---
> <p>The following graph shows overall performance when downloading static files of different sizes over Tor.
> The graph shows the range of measurements from first to third quartile, and highlights the median.
250,251c250,251
< <p>The following data file contains aggregate statistics on the performance of downloading static files of different sizes over Tor.
< These statistics are generated by the <a href="https://gitweb.torproject.org/torperf.git";>Torperf</a> tool that periodically fetches static files over Tor and records several timestamps in the process.
---
> <p>The following data file contains aggregate statistics on performance when downloading static files of different sizes over Tor.
> These statistics are generated by the <a href="https://gitweb.torproject.org/torperf.git";>Torperf</a> tool, which periodically fetches static files over Tor and records several timestamps in the process.
275c275
< The data file contains the absolute number of 10-second intervals per relay aggregated over 24-hour periods.</p>
---
> The data file contains the absolute number of 10-second intervals per relay, aggregated over 24-hour periods.</p>
_______________________________________________
tor-dev mailing list
tor-dev@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev