[metrics-lib/release] Add tutorial link and examples. - tor-commits

17 May 2017

commit b1ea6416271a53d394dd4c7eb4de8dbc73d5dbca
Author: Karsten Loesing karsten.loesing@gmx.net
Date:   Mon Mar 13 20:18:21 2017 +0100
Add tutorial link and examples.
---
 README.md                                          |  8 +++
 .../examples/ConsensusWeightByVersion.java         | 62 ++++++++++++++++++++++
 .../resources/examples/DownloadConsensuses.java    | 25 +++++++++
 .../resources/examples/PluggableTransports.java    | 48 +++++++++++++++++
 4 files changed, 143 insertions(+)

diff --git a/README.md b/README.md
index 2208379..0cc93d8 100644
--- a/README.md
+++ b/README.md
@@ -89,3 +89,11 @@ jarsigner -verify descriptor-1.0.0.jar
 jarsigner -verify descriptor-1.0.0-sources.jar
 ```
+
+Tutorial
+--------
+
+The Metrics website has a tutorial for getting started with metrics-lib:
+
+https://metrics.torproject.org/metrics-lib.html
+
diff --git a/src/main/resources/examples/ConsensusWeightByVersion.java b/src/main/resources/examples/ConsensusWeightByVersion.java
new file mode 100644
index 0000000..3b8495d
--- /dev/null
+++ b/src/main/resources/examples/ConsensusWeightByVersion.java
@@ -0,0 +1,62 @@
+/* Copyright 2017 The Tor Project
+ * See LICENSE for licensing information */
+
+import org.torproject.descriptor.*;
+
+import java.io.File;
+import java.util.*;
+
+public class ConsensusWeightByVersion {
+  public static void main(String[] args) {
+
+    // Download consensuses.
+    DescriptorCollector descriptorCollector = DescriptorSourceFactory.createDescriptorCollector();
+    descriptorCollector.collectDescriptors("https://collector.torproject.org", new String[] { "/recent/relay-descriptors/consensuses/" }, 0L, new File("descriptors"), false);
+
+    // Keep local counters for extracted descriptor data.
+    long totalBandwidth = 0L;
+    SortedMap<String, Long> bandwidthByVersion = new TreeMap<>();
+
+    // Read descriptors from disk.
+    DescriptorReader descriptorReader = DescriptorSourceFactory.createDescriptorReader();
+
+    // Add the directory with descriptors to the descriptor reader.
+    descriptorReader.addDirectory(new File("descriptors/recent/relay-descriptors/consensuses"));
+    Iterator<DescriptorFile> descriptorFiles = descriptorReader.readDescriptors();
+    while (descriptorFiles.hasNext()) { // Iterate over all descriptor files found.
+      DescriptorFile descriptorFile = descriptorFiles.next();
+
+      // Now, iterate over the descriptors contained in the file.
+      for (Descriptor descriptor : descriptorFile.getDescriptors()) {
+        if (!(descriptor instanceof RelayNetworkStatusConsensus)) {
+          // We're only interested in consensuses.
+          continue;
+        }
+        RelayNetworkStatusConsensus consensus = (RelayNetworkStatusConsensus) descriptor;
+        for (NetworkStatusEntry entry : consensus.getStatusEntries().values()) {
+          String version = entry.getVersion();
+          if (!version.startsWith("Tor ") || version.length() < 9) {
+            // We're only interested in a.b.c type versions for this example.
+            continue;
+          }
+          // Remove the 'Tor ' prefix and anything starting at the patch level.
+          version = version.substring(4, 9);
+          long bandwidth = entry.getBandwidth();
+          totalBandwidth += bandwidth;
+          if (bandwidthByVersion.containsKey(version)) {
+            bandwidthByVersion.put(version, bandwidth + bandwidthByVersion.get(version));
+          } else {
+            bandwidthByVersion.put(version, bandwidth);
+          }
+        }
+      }
+    }
+
+    // Print out fractions of consensus weight by Tor version.
+    if (totalBandwidth > 0L) {
+      for (Map.Entry<String, Long> e : bandwidthByVersion.entrySet()) {
+        System.out.printf("%s -> %4.1f%%%n", e.getKey(), (100.0 * (double) e.getValue() / (double) totalBandwidth));
+      }
+    }
+  }
+}
diff --git a/src/main/resources/examples/DownloadConsensuses.java b/src/main/resources/examples/DownloadConsensuses.java
new file mode 100644
index 0000000..a592928
--- /dev/null
+++ b/src/main/resources/examples/DownloadConsensuses.java
@@ -0,0 +1,25 @@
+/* Copyright 2017 The Tor Project
+ * See LICENSE for licensing information */
+
+import org.torproject.descriptor.*;
+
+import java.io.File;
+
+public class DownloadConsensuses {
+  public static void main(String[] args) {
+
+    // Download consensuses published in the last 72 hours, which will take up to five minutes and require several hundred MB on the local disk.
+    DescriptorCollector descriptorCollector = DescriptorSourceFactory.createDescriptorCollector();
+    descriptorCollector.collectDescriptors(
+        // Download from Tor's main CollecTor instance,
+        "https://collector.torproject.org",
+        // include only network status consensuses
+        new String[] { "/recent/relay-descriptors/consensuses/" },
+        // regardless of last-modified time,
+        0L,
+        // write to the local directory called descriptors/,
+        new File("descriptors"),
+        // and don't delete extraneous files that do not exist remotely anymore.
+        false);
+  }
+}
diff --git a/src/main/resources/examples/PluggableTransports.java b/src/main/resources/examples/PluggableTransports.java
new file mode 100644
index 0000000..88e7eb6
--- /dev/null
+++ b/src/main/resources/examples/PluggableTransports.java
@@ -0,0 +1,48 @@
+/* Copyright 2017 The Tor Project
+ * See LICENSE for licensing information */
+
+import org.torproject.descriptor.*;
+
+import java.io.File;
+import java.util.*;
+
+public class PluggableTransports {
+  public static void main(String[] args) {
+
+    DescriptorCollector descriptorCollector = DescriptorSourceFactory.createDescriptorCollector();
+    descriptorCollector.collectDescriptors("https://collector.torproject.org", new String[] { "/recent/bridge-descriptors/extra-infos/" }, 0L, new File("descriptors"), false);
+
+    Set<String> observedFingerprints = new HashSet<>();
+    SortedMap<String, Integer> countedTransports = new TreeMap<>();
+
+    DescriptorReader descriptorReader = DescriptorSourceFactory.createDescriptorReader();
+    descriptorReader.addDirectory(new File("descriptors/recent/bridge-descriptors/extra-infos"));
+    Iterator<DescriptorFile> descriptorFiles = descriptorReader.readDescriptors();
+    while (descriptorFiles.hasNext()) {
+      DescriptorFile descriptorFile = descriptorFiles.next();
+      for (Descriptor descriptor : descriptorFile.getDescriptors()) {
+        if (!(descriptor instanceof BridgeExtraInfoDescriptor)) {
+          continue;
+        }
+        BridgeExtraInfoDescriptor extraInfo = (BridgeExtraInfoDescriptor) descriptor;
+        String fingerprint = extraInfo.getFingerprint();
+        if (observedFingerprints.add(fingerprint)) {
+          for (String transport : extraInfo.getTransports()) {
+            if (countedTransports.containsKey(transport)) {
+              countedTransports.put(transport, 1 + countedTransports.get(transport));
+            } else {
+              countedTransports.put(transport, 1);
+            }
+          }
+        }
+      }
+    }
+
+    if (!observedFingerprints.isEmpty()) {
+      double totalObservedFingerprints = observedFingerprints.size();
+      for (Map.Entry<String, Integer> e : countedTransports.entrySet()) {
+        System.out.printf("%20s -> %4.1f%%%n", e.getKey(), (100.0 * (double) e.getValue() / totalObservedFingerprints));
+      }
+    }
+  }
+}

    