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)); + } + } + } +}