nsITelemetry

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

Attributes

Constants

Methods

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.

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.

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.

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

• bug 649502 - Expose histograms to JS
• bug 585196 - Telemetry infrastructure
• bug 668312 - Report only probes defined in Histograms.json
• bug 1069874 - Add keyed histogram types