Merge branch 'task/31780' into develop

0751ad71 · Philipp Winter · e5f83a44 · 39b6285b · 0751ad71 · 0751ad71
Unverified Commit 0751ad71 authored Oct 3, 2019 by Philipp Winter
--- a/CHANGELOG
+++ b/CHANGELOG
+Changes in version A.B.C - YYYY-MM-DD
+
+        * FIXES https://bugs.torproject.org/31780
+        We implemented BridgeDB's metrics in #9316 but haven't specified its
+        format until now.  In addition to adding a specification, this patch
+        also makes our implementation consistent with our (slightly updated)
+        specification.
+
 Changes in version 0.8.2 - 2019-09-20

        Updated translations for the following languages:

--- a/bridgedb/main.py
+++ b/bridgedb/main.py
@@ -85,7 +85,7 @@ def writeMetrics(filename, measurementInterval):
    logging.debug("Dumping metrics to file: '%s'" % filename)

    try:
-        with open(filename, 'a') as fh:
+        with open(filename, 'w') as fh:
            metrics.export(fh, measurementInterval)
    except IOError as err:
        logging.error("Failed to write metrics to '%s': %s" % (filename, err))

--- a/bridgedb/metrics.py
+++ b/bridgedb/metrics.py
@@ -9,7 +9,7 @@
 # :license: see LICENSE for licensing information
 # _____________________________________________________________________________

-"""API for keeping track of BridgeDB statistics, e.g., the demand for bridges
+"""API for keeping track of BridgeDB metrics, e.g., the demand for bridges
 over time.
 """

@@ -53,9 +53,9 @@ SUBNET_CTR_PREFIX_LEN = 20
 # All of the pluggable transports BridgeDB currently supports.
 SUPPORTED_TRANSPORTS = None

-# Major and minor version number for our statistics format.
-METRICS_MAJOR_VERSION = 1
-METRICS_MINOR_VERSION = 0
+# Version number for our metrics format.  We increment the version if our
+# format changes.
+METRICS_VERSION = 1


 def setProxies(proxies):
@@ -120,11 +120,10 @@ def export(fh, measurementInterval):
        logging.debug("Metrics module knows about %d proxies." % numProxies)

    now = datetime.datetime.utcnow()
-    fh.write("bridgedb-stats-end %s (%d s)\n" % (
+    fh.write("bridgedb-metrics-end %s (%d s)\n" % (
             now.strftime("%Y-%m-%d %H:%M:%S"),
             measurementInterval))
-    fh.write("bridgedb-stats-version %d.%d\n" % (METRICS_MAJOR_VERSION,
-                                                 METRICS_MINOR_VERSION))
+    fh.write("bridgedb-metrics-version %d\n" % METRICS_VERSION)

    httpsLines = httpsMetrix.getMetrics()
    for line in httpsLines:

--- a/bridgedb/test/test_metrics.py
+++ b/bridgedb/test/test_metrics.py
@@ -110,8 +110,8 @@ class StateTest(unittest.TestCase):
        self.assertTrue(len(pseudo_fh.getvalue()) > 0)

        lines = pseudo_fh.getvalue().split("\n")
-        self.assertTrue(lines[0].startswith("bridgedb-stats-end"))
-        self.assertTrue(lines[1].startswith("bridgedb-stats-version"))
+        self.assertTrue(lines[0].startswith("bridgedb-metrics-end"))
+        self.assertTrue(lines[1].startswith("bridgedb-metrics-version"))
        self.assertTrue(lines[2] ==
                        "bridgedb-metric-count https.obfs4.de.success.None 10")


--- a/doc/bridgedb-metrics-spec.txt
+++ b/doc/bridgedb-metrics-spec.txt
+                      BridgeDB metrics (version 1)
+
+BridgeDB exports usage metrics once every 24 hours.  These metrics
+encode how many approximate successful/failed requests BridgeDB has seen
+per distribution mechanism, per pluggable transport, per country code or
+email provider.  For example, one of these metrics lines can tell us
+that over the last 24 hours, BridgeDB has seen between 21 and 30
+successful requests for obfs4 over moat from Zimbabwe.
+
+This section specifies the format of BridgeDB's metrics.  Each metrics
+file is formatted as follows:
+
+  "bridgedb-metrics-end" YYYY-MM-DD HH:MM:SS (NSEC s) NL
+      [At start, exactly once.]
+
+      YYYY-MM-DD HH:MM:SS defines the end (in UTC) of the included
+      measurement interval of length NSEC seconds (86400 seconds by
+      default).
+
+      Example:
+        bridgedb-metrics-end 2019-09-18 00:33:44 (86400 s)
+
+  "bridgedb-metrics-version" VERSION NL
+      [Exactly once.]
+
+      VERSION determines the version of the metrics format.  As the
+      format changes over time, we will increment VERSION.  The latest
+      version is 1 -- the first iteration of the metrics format.
+
+      Example:
+        bridgedb-metrics-version 1
+
+  "bridgedb-metric-count" METRIC_KEY COUNT NL
+      [Any number.]
+
+      METRIC_KEY determines a metrics key, which consists of several
+      fields, separated by a period:
+
+      DISTRIBUTION "." TRANSPORT "." CC/EMAIL "." "success" | "fail" "." RESERVED
+
+      DISTRIBUTION is BridgeDB's distribution mechanism, which includes
+      "https", "email", and "moat".  These distribution mechanisms may
+      change in the future.
+
+      TRANSPORT refers to a pluggable transport protocol.  This includes
+      "obfs2", "obfs3", "obfs4", "scramblesuit", and "fte".  These
+      pluggable transports will change in the future.
+
+      CC/EMAIL refers to a two-letter country code of the user's IP
+      address iff DISTRIBUTION is "moat" or "https"; or to an email
+      provider iff DISTRIBUTION is "email".  We use two reserved country
+      codes, "??" and "zz".  "??" denotes that we couldn't map an IP
+      address to its country, e.g., because our geolocation API was
+      unable to.  "zz" denotes a proxy IP address, e.g., Tor exit
+      relays.  The two allowed email providers are "gmail" and "riseup".
+
+      The next field is either "success" or "fail", depending on if the
+      BridgeDB request was successful or not.  A request is successful
+      if BridgeDB attempts to provide the user with bridges, even if
+      BridgeDB currently has no bridges available.  A request has failed
+      if BridgeDB won't provide the user with bridges, for example, if
+      the user could not solve the CAPTCHA.
+
+      The field RESERVED is reserved for an anomaly score.  It is
+      currently set to "none" and should be ignored by implementations.
+
+      COUNT is the approximate number of user requests for the given
+      METRIC_KEY.  We round up the number of requests to the next
+      multiple of 10 to preserve some user privacy.
+
+      Examples:
+        bridgedb-metric-count https.scramblesuit.zz.fail.none 100
+        bridgedb-metric-count moat.obfs4.??.success.none 3550
+        bridgedb-metric-count email.fte.gmail.fail.none 10