FirefoxOS/Metrics/CustomMetrics

Custom Metrics

Custom metrics are metrics that are recorded in 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 for each app when Custom Metrics is enabled.

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' - AppUsageMetrics are collected, and 'Enhanced' - AppUsageMetrics + 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/advanced_telemetry_helper.js"></script>
• <script defer src="/shared/js/advanced_telemetry_helper.js"></script>

Include AdvancedTelemetryHelper in the globals

There are currently three types of metrics that can be used as part of Custom Metrics:

• Counter: This is a simple counter that increments by 1 each time it's called
• Linear: This type of metric creates a linear 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: This type of metric creates an exponential distributed set of buckets ranging between min and max. You can specify the min, max, and buckets.

Counter Metric Usage Example:

 // This creates the histogram counter on this metric called
 // 'mycount'
 var count = new AdvancedTelemetryHelper(ATH.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(ATH.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 bucket that holds the value 800

 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(ATH.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 800.
 exp.add(800); // The histogram now has two values, one in the 15 bucket
               // and one in the bucket that holds the value 800