                      BridgeDB metrics (version 2)

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 2 -- the second iteration of the metrics format.

      Example:
        bridgedb-metrics-version 2

  "bridgedb-metric-count" METRIC_KEY COUNT NL
      [Any number.]

      METRIC_KEY specifies a metrics key, which consists of several fields,
      separated by a period.  These fields form a hierarchy.  At the root of
      the hierarchy are our three distribution mechanisms ("https", "email",
      and "moat") and "internal", which represents BridgeDB-internal metrics.
      The hierarchy is of the following form:

      * "https"
      └─* TRANSPORT
        └─* CC
          └─* "success" | "fail"
            └─* RESERVED

      * "email"
      └─* TRANSPORT
        └─* EMAIL
          └─* "success" | "fail"
            └─* RESERVED

      * "moat"
      └─* TRANSPORT
        └─* CC
          └─* "success" | "fail"
            └─* RESERVED

      * "internal"
      ├─* "handouts"
      │ ├─* "min"
      │ ├─* "max"
      │ ├─* "median"
      │ ├─* "quartile1"
      │ ├─* "quartile3"
      │ ├─* "lower-whisker"
      │ ├─* "upper-whisker"
      │ ├─* "ipv4"
      │ └─* "ipv6"
      │
      └─* TRANSPORT
        ├─* "empty-response"
        └─* SUBRING

      Strings in between quotes (e.g., "handouts") are literals and show up in
      the hierarchy as is.  Upper-case strings (e.g., TRANSPORT) are
      placeholders, which are explained below.  The internal.handouts 
      metrics provide statistics on how often a given bridge was handed out 
      during the measurement interval. Bridges that were not handed out will 
      not be part of these metrics.

      TRANSPORT refers to a pluggable transport protocol.  This includes
      "obfs2", "obfs3", "obfs4", "scramblesuit", and "fte".  These
      pluggable transports will change in the future.  This field also includes 
      "unallocated" when reporting internal metrics to report on bridges left 
      unallocated as configured.

      CC refers to a two-letter country code of the user's IP address.  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.

      EMAIL refers to an email provider.  The two currently-supported email
      providers are "gmail" and "riseup".

      The field RESERVED is reserved for an anomaly score.  It is currently set
      to "none" and should be ignored by implementations.
      
      SUBRING refers to a subring of a hashring that bridges are arranged into 
      during distribution.

      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.  Some metrics key are not
      rounded up to the next multiple of ten because they are not sensitive.

      One label either takes on the value "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.

      Here are several 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
        bridgedb-metric-count internal.handouts.ipv4 20
        bridgedb-metric-count internal.moat.empty-response 10
        bridgedb-metric-count internal.handouts.min 23
        bridgedb-metric-count internal.https.byipv6-bysubring1of4 40
