[tor-commits] [stem/master] Example for getting number of relays a bw auth has a measurement for

[atagar at torproject.org]

commit ed9b401f0a553274e07055b067406d255e61bc98
Author: Damian Johnson <atagar at torproject.org>
Date:   Fri Aug 29 09:17:05 2014 -0700

    Example for getting number of relays a bw auth has a measurement for
    
    Including a script I just whipped up for Sebastian to see if there was an issue
    with the bandwidth authorities. This gives a fine spot to describe a bit more
    about how the Tor network works.
---
 docs/tutorials/double_double_toil_and_trouble.rst  |    5 ++
 .../examples/votes_by_bandwidth_authorities.rst    |   64 ++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/docs/tutorials/double_double_toil_and_trouble.rst b/docs/tutorials/double_double_toil_and_trouble.rst
index 4d1a672..06a6c08 100644
--- a/docs/tutorials/double_double_toil_and_trouble.rst
+++ b/docs/tutorials/double_double_toil_and_trouble.rst
@@ -97,3 +97,8 @@ Descriptors
   Compares the votes of two directory authorities, in this case moria1 and
   maatuska with a special interest in the 'Running' flag.
 
+* `Votes by Bandwidth Authorities <examples/votes_by_bandwidth_authorities.html>`_
+
+  Provides information about the current votes from Tor's Bandwidth
+  Authorities.
+
diff --git a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
new file mode 100644
index 0000000..f1a4d67
--- /dev/null
+++ b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
@@ -0,0 +1,64 @@
+Votes by Bandwidth Authorities
+==============================
+
+.. image:: /_static/buttons/back.png
+   :target: ../double_double_toil_and_trouble.html
+
+Tor takes into account a relay's throughput when picking a route through the
+Tor network for its circuits. That is to say large, fast relays receive more
+traffic than small ones since they can better service the load.
+
+To determine a relay's throughput special authorities, called **bandwidth
+authorities**, take periodic measurements using them. The `lifecycle of new Tor
+relays <https://blog.torproject.org/blog/lifecycle-of-a-new-relay>`_ is a bit
+more complicated than that, but that's the general idea.
+
+Bandwidth authorities include their measurements in their votes. The following
+gets their current votes then prints how many relays it had a measurement for.
+
+::
+
+  from stem.descriptor import remote
+
+  # request votes from all the bandwidth authorities
+
+  queries = {}
+  downloader = remote.DescriptorDownloader()
+
+  for authority in remote.get_authorities().values():
+    if authority.nickname not in ('moria1', 'gabelmoo', 'maatuska', 'tor26'):
+      continue  # not a bandwidth authority
+
+    queries[authority.nickname] = downloader.query(
+      '/tor/status-vote/current/authority',
+      endpoints = [(authority.address, authority.dir_port)],
+    )
+
+  for authority_name, query in queries.items():
+    try:
+      print "Getting %s's vote from %s:" % (authority_name, query.download_url)
+
+      measured, unmeasured = 0, 0
+
+      for desc in query.run():
+        if desc.measured:
+          measured += 1
+        else:
+          unmeasured += 1
+
+      print '  %i measured entries and %i unmeasured' % (measured, unmeasured)
+    except Exception as exc:
+      print "  failed to get the vote (%s)" % exc 
+
+::
+
+  % python bandwidth_auth_measured_counts.py
+  Getting gabelmoo's vote from http://212.112.245.170:80/tor/status-vote/current/authority:
+    5935 measured entries and 1332 unmeasured
+  Getting tor26's vote from http://86.59.21.38:80/tor/status-vote/current/authority:
+    5735 measured entries and 1690 unmeasured
+  Getting moria1's vote from http://128.31.0.39:9131/tor/status-vote/current/authority:
+    6647 measured entries and 625 unmeasured
+  Getting maatuska's vote from http://171.25.193.9:443/tor/status-vote/current/authority:
+    6313 measured entries and 1112 unmeasured
+