Tor Metrics Library API, which is provided and supported by Tor's Metrics
Team, is a library to obtain and process descriptors containing Tor
network data. It is the main Java tool for processing Tor descriptors
and provides a standard API consisting of interfaces and a reference
implementation for all of them.
Most Tor descriptors understood by this library are specified in the
Tor
directory protocol, version 3 or in the earlier
version 2 or
version 1
of that document.
Other descriptors are specified on the
CollecTor website.
The interfaces in
{@code org.torproject.descriptor}
as well as their implementations in the
{@code org.torproject.descriptor.impl} package were driven by two main
goals originating from the primary use case to make Tor network data
accessible for statistical analysis:
- Complete coverage: This library is supposed to cover the
complete range of Tor descriptors made available by the
CollecTor service.
- Runtime and memory efficiency: Processing large amounts of
descriptors in bulk is supposed to be efficient in terms of runtime and
required memory.
At the same time the current design and implementation were done with a
number of non-goals in mind, even though some of these might turn into
goals in the future:
- Verification: The descriptor parser performs some basic
verifications of descriptor formats, but no cryptographic verifications.
It may not even be possible to write a cryptographic verification tool
using parsed descriptor contents, though this has not been attempted
yet.
- Potentially lossy conversion: Descriptor contents may be
converted to a format that is easier to process, even if that conversion
makes it harder or impossible to re-create the original descriptor
contents from a parsed descriptor.
- Generating descriptors: This library does not contain any
functionality to generate new descriptors for testing or related purposes,
neither from previously set data nor randomly.
- Writing descriptors: This library does not support writing
descriptors to the file system or a database, both of which are left to
the application. Stated differently, there are no descriptor sinks that
would correspond to the provided descriptor sources.
Hints about using Tor Metrics Library can be found in the
{@code org.torproject.descriptor} package description.
Contact and further information: