MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla
Your Search Results

    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

    Last updated by: gfritzsche,