Tor Metrics Library 2.26.0-dev.4399c7d API Documentation
Tor Metrics Library API, which is provided and supported by Tor's Network Health 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
org.torproject.descriptor
as well as their implementations in the
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
org.torproject.descriptor package description.
Contact and further information:
| Package | Description |
|---|---|
| org.torproject.descriptor |
Interfaces and essential classes for obtaining and processing Tor
descriptors.
|