nsITelemetry

A service to gather performance data that can be tracked over time to allow generating histograms.
1.0
33.0.2
Introduced
Gecko 6.0
Inherits from: nsISupports Last changed in Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

Implemented by: @mozilla.org/base/telemetry;1 as a service:

let telemetry = Components.classes["@mozilla.org/base/telemetry;1"]
                .getService(Components.interfaces.nsITelemetry);

Method overview

jsval getHistogramById(in ACString id);
jsval newHistogram(in ACString name, in ACString expiration, in unsigned long histogram_type, [optional] in PRUint32 min, [optional] in PRUint32 max, [optional] in PRUint32 bucket_count);
jsval getKeyedHistogramById(in ACString id); Requires Gecko 34.0
jsval newKeyedHistogramById(in ACString id, in ACString name, in ACString expiration, in unsigned long histogram_type, [optional] in PRUint32 min, [optional] in PRUint32 max, [optional] in PRUint32 bucket_count); Requires Gecko 34.0
void registerAddonHistogram(in ACString addon_id, in ACString name, in unsigned long histogram_type, [optional] in uint32_t min, [optional] in uint32_t max, [optional] in uint32_t bucket_count);
jsval getAddonHistogram(in ACString addon_id, in ACString name);
void unregisterAddonHistograms(in ACString addon_id);

Attributes

Attribute Type Description
canRecord boolean Set this to false to disable gathering of telemetry statistics.
histogramSnapshots

An object containing a snapshot from all of the currently registered histograms. { name1: {data1}, name2:{data2}...} where data consists of the following properties:

  • min - Minimal bucket size
  • max - Maximum bucket size
  • histogram_type - HISTOGRAM_EXPONENTIAL or HISTOGRAM_LINEAR
  • counts - An array representing the values of buckets in the histogram.
  • ranges - An array with corresponding bucket sizes.
  • sum - Sum of the counts array.
  • static - true for histograms defined in Histograms.json, false for ones defined with newHistogram().
Read only.

Constants

Constant Value Description
HISTOGRAM_EXPONENTIAL 0 Buckets increase exponentially.
HISTOGRAM_LINEAR 1 Buckets increase linearly.
HISTOGRAM_BOOLEAN 2 For storing 0/1 values.
HISTOGRAM_FLAG 3 For storing a single value; its count is always == 1.
HISTOGRAM_COUNT 4 For storing a single count. Requires Gecko 35.0

Methods

Requires Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

getHistogramById()

Same as newHistogram(), but for histograms registered in Histograms.json.

jsval getHistogramById(
  in ACString id
);
Parameters
id
Unique identifier from toolkit/components/telemetry/Histograms.json.
Return value

The returned object has the following functions:

  • add(value) - Adds an integer value to the appropriate bucket
  • snapshot() - Returns a snapshot of the histogram with the same data fields as in histogramSnapshots.

newHistogram()

Creates and returns a new histogram object. The returned object provides methods you can use to add values to the histogram as well as to retrieve snapshots of the histogram.

Note: As of Gecko 7.0, telemetry histograms defined with newHistogram will not be reported in the telemetry ping.

jsval newHistogram(
  in ACString name,
  in ACString expiration,
  in unsigned long histogram_type,
  [optional] in PRUint32 min,
  [optional] in PRUint32 max,
  [optional] in PRUint32 bucket_count
);
Parameters
name
Unique histogram name.
expiration
The version number in which the histogram expires, e.g. "30"; a version number of type "N" and "N.0" is automatically converted to "N.0a1" in order to expire the histogram also in the development channels. A telemetry probe acting on an expired histogram will be considered a non-op. For histograms that never expire the value "never" can be used.
histogram_type
HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, HISTOGRAM_BOOLEAN, HISTOGRAM_FLAG or HISTOGRAM_COUNT.
min
Minimal bucket size.
Note: The value must be >=1. Special bucket 0 is created for values that are smaller than min.
max
Maximum bucket size.
bucket_count
Number of buckets in the histogram.
Return value

The returned object has the following functions:

  • add(value) - Adds an integer value to the appropriate bucket
  • snapshot() - Returns a snapshot of the histogram with the same data fields as in histogramSnapshots.

Requires Gecko 34.0 (Firefox 34.0 / Thunderbird 34.0 / SeaMonkey 2.31)

getKeyedHistogramById()

Same as newKeyedHistogram(), but for histograms registered in Histograms.json.

jsval getHistogramById(
  in ACString id
);
Parameters
id
Unique identifier from toolkit/components/telemetry/Histograms.json.
Return value

The returned object has the following functions:

  • add(key, [optional] value) - Adds an integer value to the appropriate bucket. For count histograms providing the value is optional.
  • snapshot([optional] key) - Returns a snapshot of the keyed histogram or (if key is provided) the snapshot of the contained histogram with that key.
  • keys() - Returns an array with the string keys of the currently registered histograms.
  • clear() - Clear out the registered histograms and keys.

Requires Gecko 34.0 (Firefox 34.0 / Thunderbird 34.0 / SeaMonkey 2.31)

newKeyedHistogram()

jsval newKeyedHistogram(
  in ACString id,
  in ACString expiration,
  in unsigned long histogram_type,
  [optional] in uint32_t min,
  [optional] in uint32_t max,
  [optional] in uint32_t bucket_count
);
Parameters
id
Unique identifier.
expiration
The version number in which the histogram expires, e.g. "30"; a version number of type "N" and "N.0" is automatically converted to "N.0a1" in order to expire the histogram also in the development channels. A telemetry probe acting on an expired histogram will be considered a non-op. For histograms that never expire the value "never" can be used.
histogram_type
HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, HISTOGRAM_BOOLEAN, HISTOGRAM_FLAG or HISTOGRAM_COUNT.
min
Minimal bucket size.
Note: The value must be >=1. Special bucket 0 is created for values that are smaller than min.
max
Maximum bucket size.
bucket_count
Number of buckets in the histogram.
Return value

The returned object has the following functions:

  • add(key, [optional] value) - Adds an integer value to the appropriate bucket. For count histograms providing the value is optional.
  • snapshot([optional] key) - Returns a snapshot of the keyed histogram or (if key is provided) the snapshot of the contained histogram with that key.
  • keys() - Returns an array with the string keys of the currently registered histograms.
  • clear() - Clear out the registered histograms and keys.

Example

You can find detailed information on adding a new Telemetry probe and recording Telemetry data at Adding a new Telemetry probe [en-US].

The following code sample shows some of the functionality of the Telemetry interface. It creates two different kinds of Telemetry histograms at runtime, records measurements and then outputs the state of the histograms. These histograms would be reported in the Telemetry ping.

const Telemetry = Components.classes["@mozilla.org/base/telemetry;1"]
                  .getService(Components.interfaces.nsITelemetry);
const CONNECTION_TIME = "Connection time (ms)";
const BINARY_CHOICE = "Some binary choice (Yes, No)";
Telemetry.newHistogram(CONNECTION_TIME, 1, 300, 10, Telemetry.HISTOGRAM_EXPONENTIAL).add(233);
Telemetry.newHistogram(BINARY_CHOICE, 1, 2, 3, Telemetry.HISTOGRAM_BOOLEAN).add(1);
let histograms = Telemetry.histogramSnapshots;
dump(uneval(histograms[CONNECTION_TIME]) + "\n");
dump(uneval(histograms[BINARY_CHOICE]) + "\n");

See also

Document Tags and Contributors

 Contributors to this page: gfritzsche, Sheppy, kscarfone, Vladan, mreid, mnoorenberghe, trevorh, Tglek
 Last updated by: gfritzsche,