[tor-commits] [onionperf/develop] Update README and CHANGELOG

[karsten at torproject.org]

commit 1b638e34cb0476148dcf93b43b58b54a30c27428
Author: Ana Custura <ana at netstat.org.uk>
Date:   Thu Sep 10 14:46:10 2020 +0100

    Update README and CHANGELOG
---
 CHANGELOG.md |  5 +++++
 README.md    | 10 +++++++---
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ebd43e1..a7d5005 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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
 
diff --git a/README.md b/README.md
index 224972c..13a9eee 100644
--- a/README.md
+++ b/README.md
@@ -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