GitLab is used only for code review, issue tracking and project management. Canonical locations for source code are still https://gitweb.torproject.org/ https://git.torproject.org/ and git-rw.torproject.org.

Commit 1b638e34 authored by Ana Custura's avatar Ana Custura

Update README and CHANGELOG

parent d0660c18
......@@ -3,6 +3,11 @@
- Add a new `onionperf filter` mode that takes an OnionPerf analysis
results file or directory as input, applies filters, and produces
new OnionPerf analysis results file(s) as output.
- Bump the analysis version number to 4.0 for new analyses and analyses
produced by the `onionperf filter` mode
- Analyses produced by the `onionperf filter` mode have additional filter
metadata defined in a new 'filters' field, and an optional 'filtered\_out'
field per tor circuit
# Changes in version 0.6 - 2020-08-08
......
......@@ -254,10 +254,12 @@ onionperf analyze --help
```
### Filtering measurement results
OnionPerf measurement results can be filtered based on Tor relay fingerprints.
The `filter` mode takes a list of fingerprints and one or more existing analysis files as inputs, and outputs new analysis files containing only the `tgen` results obtained over a Tor circuit path which includes or excludes fingerprints in the input list.
The `filter` subcommand is typically used in combination with the `visualize` subcommand. The workflow is to filter out any Tor streams/circuits that are not desired then visualize only those measurements with an existing mapping between TGen transfers/streams and Tor streams/circuits.
Where excluding fingerprints, if ANY relay fingerprint is matched, the measurement is discarded. Where including fingerprints, ALL relay fingerprints in a path must match for the measurement to be retained.
Currently, OnionPerf measurement results can be filtered based on Tor relay fingerprints, although support for filtering TGen based on transfers/streams may be added in the future.
The `filter` mode takes a list of fingerprints and one or more existing analysis files as inputs, and outputs new analysis files which include, unchanged, the Tor results obtained over a Tor circuit path which includes or excludes fingerprints in the input list. All other Tor results are also included in the file, but are marked as 'filtered\_out'.
Filter metadata detailing the filter type and path to the input list used is also included in the analysis file.
For example, the analysis file produced above can be filtered with the following command, which retains measurements based on fingerprints contained in the file 'fingerprints.txt':
......@@ -290,6 +292,8 @@ As a result, two files are written to the current working directory:
- `onionperf.viz.$datetime.csv` contains visualized data in a CSV file format; and
- `onionperf.viz.$datetime.pdf` contains visualizations in a PDF file format.
For analysis files containing tor circuit filters, only measurements with an existing mapping between TGen transfers/streams Tor streams/circuits which have not been marked as 'filtered\_out' are visualized.
Similar to the other modes, OnionPerf's `visualize` mode has command-line parameters for customizing the visualization step:
```shell
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment