freedom.js Anonymized Metrics

freedom.js module for anonymized metric collection.

This module encapuslates the logic presented in RAPPOR, a technique for randomize aggregatable privacy-preserving Ordinal responses.

Usage

1. Add anonmetrics.json as a dependency of your module, using the metrics API.

2. Establish the metrics you want to monitor, and instantiate anonmetrics with this definition. The definition format is described in the Metrics Definition section.

   var metrics = freedom.anonMetrics({
     "name": "myMetrics",
     "definition": {
       ...
     }
   });

3. Create metrics instances as needed, using the defined name.

   var metrics = freedom.anonMetrics("myMetrics");

4. Report a metric values at appropriate points.

   metrics.report('successes', 1);
   metrics.report('bandwidth', observedBandwidth);

5. Extract a report of current metric information for use in a report.

   metrics.retrieve().then(function(report) {
     ...
   });

Metrics Definition

A declarative description of how the anonmetrics module should process reported data for your application is passed to the constructor once throughout the modules making up your application. Other instances can report metrics before this definition is provided, so you don't need to worry about race conditions, but the definition does need to be provided in the lifetime of the module or reports will not be saved - since storage will only record statistics and not raw reported values.

The defintion of metrics follow the following format:

"country": {
  "type": "string",
},
"connections": {
  "type": "logarithmic",
  "base": 10
}

Encoding Strategies

Logarithmic

Appropriate for positive integer values where the order of magnitude is interesting.

String

Appropriate for arbitrary strings, where relative frequencies of known exact values can be compared.

Development

Pull requests are happily taken. Automated tests are designed to enforce correctness and code-quality of the repository.