toolkit/components/telemetry/nsITelemetry.idlScriptable
A service to gather performance data that can be tracked over time to allow generating histograms.
1.0
66
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 snapshotHistograms(in uint32_t aDataset, in boolean aSubsession, in boolean aClear);
jsval getKeyedHistogramById(in ACString id);
void captureStack(in ACString name);
jsval snapshotCapturedStacks([optional] in boolean clear);
nsISupports getLoadedModules();
jsval snapshotKeyedHistograms(in uint32_t aDataset, in boolean aSubsession, in boolean aClear);
void setHistogramRecordingEnabled(in ACString id, in boolean enabled);
void asyncFetchTelemetryData(in nsIFetchTelemetryDataCallback aCallback);
double msSinceProcessStart();
void scalarAdd(in ACString aName, in jsval aValue);
void scalarSet(in ACString aName, in jsval aValue);
void scalarSetMaximum(in ACString aName, in jsval aValue);
jsval snapshotScalars(in uint32_t aDataset, [optional] in boolean aClear);
void keyedScalarAdd(in ACString aName, in AString aKey, in jsval aValue);
void keyedScalarSet(in ACString aName, in AString aKey, in jsval aValue);
void keyedScalarSetMaximum(in ACString aName, in AString aKey, in jsval aValue);
jsval snapshotKeyedScalars(in uint32_t aDataset, [optional] in boolean aClear);
void clearScalars(); test only
void flushBatchedChildTelemetry();
void recordEvent(in ACString aCategory, in ACString aMethod, in ACString aObject, [optional] in jsval aValue, [optional] in jsval extra);
void setEventRecordingEnabled(in ACString aCategory, in boolean aEnabled);
jsval snapshotEvents(in uint32_t aDataset, [optional] in boolean aClear);
void registerEvents(in ACString aCategory, in jsval aEventData);
void registerScalars(in ACString aCategoryName, in jsval aScalarData);
void clearEvents(); test only

Attributes

Attribute Type Description
canRecordBase boolean A flag indicating if Telemetry can record base data (FHR data). This is true if the FHR data reporting service or the self-support service is enabled.
canRecordExtended boolean A flag indicating if Telemetry is allowed to record extended data. Returns false if the user has not opted into "extended Telemetry" on the Release channel, when the user has explicitly opted out of Telemetry on Nightly/Aurora/Beta or if manually set to false during tests.
canRecordReleaseData readonly boolean A flag indicating whether Telemetry is recording release data. Does not indicate whether Telemetry will send any data. That is governed by user preference and other mechanisms.
canRecordPreReleaseData readonly boolean A flag indicating whether Telemetry is recording pre-release data. Does not indicate whether Telemetry will send any data. That is governed by user preference and other mechanisms.
histogramSnapshots jsval

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

Histogram Types

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 counter values without bucketing.
HISTOGRAM_CATEGORICAL 5 For storing enumerated values by label.

Scalar Types

Constant Value Description
SCALAR_TYPE_COUNT 0 For storing a numeric value.
SCALAR_TYPE_STRING 1 For storing a string value.
SCALAR_TYPE_BOOLEAN 2 For storing a boolean value.

Dataset Types

Constant Value Description
DATASET_RELEASE_CHANNEL_OPTOUT 0 The basic dataset that is on-by-default on all channels.
DATASET_RELEASE_CHANNEL_OPTIN 1 The extended dataset that is opt-in on release, opt-out on pre-release channels.

Methods

getHistogramById()

Get an histogram by id 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 jsval object has the following functions:

getKeyedHistogramById()

Get a keyed histogram for histograms registered in Histograms.json.

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

The returned jsval object has the following functions:

Example

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

See also