nsITelemetry 编辑

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:

• 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.

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:

• 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].

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
• bug 1426453 - Documentation of nsITelemetry not up to date