FirefoxOS/Metrics/CustomMetrics

Custom Metrics

Custom metrics are metrics that are specified by app developers and recorded within Gaia Apps. Currently, they are a part of what is called "Enhanced Metrics." Enhanced metrics includes custom metrics as well as engineering metrics. Engineering metrics are metrics that are recorded by the platform for each app.

To enable Custom Metrics, the end user must choose the "Enhanced" option when they go through the FTU experience on the device. This setting can be set to 'None' - No metrics are collected, 'Basic' - App Usage Metrics are collected, and 'Enhanced' - App Usage Metrics + Custom Metrics + Engineering Metrics are collected. This setting may be changed under the Settings|Improve Firefox OS menu. Note that if 'Enhanced' is not selected then neither Custom Metrics nor Engineering Metrics will be collected.

Currently, Custom metrics are available for certified apps only.

How to Add

To add custom metrics, here is a list of steps:

Add the following to your app (e.g. index.html)

• <script defer src="/shared/js/settings_listener.js"></script>
• <script defer src="/shared/js/advanced_telemetry_helper.js"></script>

Include AdvancedTelemetryHelper in the "globals" section of the JavaScript file(s) where custom metrics are being recorded.

The following categories can be used to represent custom metric data:

• Counter: A simple counter that increments by 1 each time the metric is recorded.
• Linear: A linearly distributed set of buckets which range between min and max. You can specify the number of buckets as well as the min and max.
• Exponential: An exponentially distributed set of buckets ranging between min and max. You can specify the min, max, and the number of buckets.

Counter Metric Usage Example:

 // This creates the histogram counter on this metric called
 // 'mycount'
 var count = new AdvancedTelemetryHelper(AdvancedTelemetryHelper.HISTOGRAM_COUNT, 'mycount');
 count.add(); //Increment the count. The count of the histogram is now 1.
 // DO SOMETHING
 count.add(); //Increment the count. The count of the histogram is now 2.

Linear Metric Usage Example:

 // This creates a linear histogram called 'mylinear' with minimum
 // of 1 (0 not allowed as a minimum), max of 1000, with 10 buckets.
 var linear = new AdvancedTelemetryHelper(AdvancedTelemetryHelper.HISTOGRAM_LINEAR, 'mylinear',
     1, 1000, 10);
 // This adds the value 15 to the histogram 'mylinear'
 linear.add(15);
 // DO SOMETHING
 // This adds to the existing histogram a value of 800.
 linear.add(800);
 // The histogram now has two values, one in the '15' bucket and one in the '800' bucket.

Exponential Metric Usage Example:

 // This creates an exponential histogram called 'myexp' with minimum
 // of 1 (0 not allowed as a minimum), max of 1000, with 10 buckets.
 var exp = new AdvancedTelemetryHelper(AdvancedTelemetryHelper.HISTOGRAM_EXPONENTIAL, 'myexp',
     1, 1000, 10);
 // This adds the value 15 to the histogram 'myexp'
 exp.add(15);
 // DO SOMETHING
 // This adds to the existing histogram a value of 2000.
 exp.add(2000); 
 // The histogram now has two values:
 // one in the bucket that holds the value '15'
 // and one in the bucket that holds the value '2000'