FirefoxOS/Metrics/CustomMetrics: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Fixed some typos, improved readability)
 
Line 1: Line 1:
=Custom Metrics=
=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.
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' - 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.
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.
Currently, Custom metrics are available for certified apps only.
Line 10: Line 10:


Add the following to your app (e.g. index.html)
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>
* <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" section of the JavaScript file(s) where custom metrics are being recorded.
Include AdvancedTelemetryHelper in the globals


There are currently three types of metrics that can be used as part of Custom Metrics:
The following categories can be used to represent custom metric data:
*Counter: This is a simple counter that increments by 1 each time it's called
*Counter: A simple counter that increments by 1 each time the metric is recorded.
*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.
*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: This type of metric creates an exponential distributed set of buckets ranging between min and max. You can specify the min, max, and buckets.
*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:
Counter Metric Usage Example:
   // This creates the histogram counter on this metric called
   // This creates the histogram counter on this metric called
   // 'mycount'
   // 'mycount'
   var count = new AdvancedTelemetryHelper(ATH.HISTOGRAM_COUNT, 'mycount');
   var count = new AdvancedTelemetryHelper(AdvancedTelemetryHelper.HISTOGRAM_COUNT, 'mycount');
   count.add(); //Increment the count. The count of the histogram is now 1.
   count.add(); //Increment the count. The count of the histogram is now 1.
   // DO SOMETHING
   // DO SOMETHING
   count.add(); //Increment the count. The count of the histogram is now 2.
   count.add(); //Increment the count. The count of the histogram is now 2.
  // Linear Metric Usage Example:
 
Linear Metric Usage Example:
   // This creates a linear histogram called 'mylinear' with minimum
   // This creates a linear histogram called 'mylinear' with minimum
   // of 1 (0 not allowed as a minimum), max of 1000, with 10 buckets.
   // of 1 (0 not allowed as a minimum), max of 1000, with 10 buckets.
   var linear = new AdvancedTelemetryHelper(ATH.HISTOGRAM_LINEAR, 'mylinear',
   var linear = new AdvancedTelemetryHelper(AdvancedTelemetryHelper.HISTOGRAM_LINEAR, 'mylinear',
       1, 1000, 10);
       1, 1000, 10);
   // This adds the value 15 to the histogram 'mylinear'
   // This adds the value 15 to the histogram 'mylinear'
Line 35: Line 36:
   // DO SOMETHING
   // DO SOMETHING
   // This adds to the existing histogram a value of 800.
   // This adds to the existing histogram a value of 800.
   linear.add(800); // The histogram now has two values, one in the 15 bucket
   linear.add(800);
                    // and one in the bucket that holds the value 800
  // The histogram now has two values, one in the '15' bucket and one in the '800' bucket.
   
   
  Exponential Metric Usage Example:
Exponential Metric Usage Example:
   // This creates an exponential histogram called 'myexp' with minimum
   // This creates an exponential histogram called 'myexp' with minimum
   // of 1 (0 not allowed as a minimum), max of 1000, with 10 buckets.
   // of 1 (0 not allowed as a minimum), max of 1000, with 10 buckets.
   var exp = new AdvancedTelemetryHelper(ATH.HISTOGRAM_EXPONENTIAL, 'myexp',
   var exp = new AdvancedTelemetryHelper(AdvancedTelemetryHelper.HISTOGRAM_EXPONENTIAL, 'myexp',
       1, 1000, 10);
       1, 1000, 10);
   // This adds the value 15 to the histogram 'myexp'
   // This adds the value 15 to the histogram 'myexp'
   exp.add(15);
   exp.add(15);
   // DO SOMETHING
   // DO SOMETHING
   // This adds to the existing histogram a value of 800.
   // This adds to the existing histogram a value of 2000.
   exp.add(800); // The histogram now has two values, one in the 15 bucket
   exp.add(2000);  
                // and one in the bucket that holds the value 800
  // The histogram now has two values:
 
  // one in the bucket that holds the value '15'
==Information to Identify==
  // and one in the bucket that holds the value '2000'

Latest revision as of 22:27, 13 November 2015

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'