зеркало из https://github.com/mozilla/gecko-dev.git
494 строки
14 KiB
JavaScript
494 строки
14 KiB
JavaScript
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
"use strict";
|
|
|
|
this.EXPORTED_SYMBOLS = [
|
|
"MetricsCollectionResult",
|
|
"MetricsMeasurement",
|
|
"MetricsProvider",
|
|
];
|
|
|
|
const {utils: Cu} = Components;
|
|
|
|
Cu.import("resource://gre/modules/commonjs/promise/core.js");
|
|
Cu.import("resource://services-common/log4moz.js");
|
|
|
|
|
|
/**
|
|
* Represents a measurement of data.
|
|
*
|
|
* This is how data is recorded and represented. Each instance of this type
|
|
* represents a related set of data.
|
|
*
|
|
* Each data set has some basic metadata associated with it. This includes a
|
|
* name and version.
|
|
*
|
|
* This type is meant to be an abstract base type. Child types should define
|
|
* a `fields` property which is a mapping of field names to metadata describing
|
|
* that field. This field constitutes the "schema" of the measurement/type.
|
|
*
|
|
* Data is added to instances by calling `setValue()`. Values are validated
|
|
* against the schema at add time.
|
|
*
|
|
* Field Specification
|
|
* ===================
|
|
*
|
|
* The `fields` property is a mapping of string field names to a mapping of
|
|
* metadata describing the field. This mapping can have the following
|
|
* properties:
|
|
*
|
|
* type -- A string corresponding to the TYPE_* property name describing a
|
|
* field type. The TYPE_* properties are defined on this type. e.g.
|
|
* "TYPE_STRING".
|
|
*
|
|
* optional -- If true, this field is optional. If omitted, the field is
|
|
* required.
|
|
*
|
|
* @param name
|
|
* (string) Name of this data set.
|
|
* @param version
|
|
* (Number) Integer version of the data in this set.
|
|
*/
|
|
this.MetricsMeasurement = function MetricsMeasurement(name, version) {
|
|
if (!this.fields) {
|
|
throw new Error("fields not defined on instance. You are likely using " +
|
|
"this type incorrectly.");
|
|
}
|
|
|
|
if (!name) {
|
|
throw new Error("Must define a name for this measurement.");
|
|
}
|
|
|
|
if (!version) {
|
|
throw new Error("Must define a version for this measurement.");
|
|
}
|
|
|
|
if (!Number.isInteger(version)) {
|
|
throw new Error("version must be an integer: " + version);
|
|
}
|
|
|
|
this.name = name;
|
|
this.version = version;
|
|
|
|
this.values = new Map();
|
|
}
|
|
|
|
MetricsMeasurement.prototype = {
|
|
/**
|
|
* An unsigned integer field stored in 32 bits.
|
|
*
|
|
* This holds values from 0 to 2^32 - 1.
|
|
*/
|
|
TYPE_UINT32: {
|
|
validate: function validate(value) {
|
|
if (!Number.isInteger(value)) {
|
|
throw new Error("UINT32 field expects an integer. Got " + value);
|
|
}
|
|
|
|
if (value < 0) {
|
|
throw new Error("UINT32 field expects a positive integer. Got " + value);
|
|
}
|
|
|
|
if (value >= 0xffffffff) {
|
|
throw new Error("Value is too large to fit within 32 bits: " + value);
|
|
}
|
|
},
|
|
},
|
|
|
|
/**
|
|
* A string field.
|
|
*
|
|
* Values must be valid UTF-8 strings.
|
|
*/
|
|
TYPE_STRING: {
|
|
validate: function validate(value) {
|
|
if (typeof(value) != "string") {
|
|
throw new Error("STRING field expects a string. Got " + typeof(value));
|
|
}
|
|
},
|
|
},
|
|
|
|
/**
|
|
* Set the value of a field.
|
|
*
|
|
* This is ultimately how fields are set. All field sets should go through
|
|
* this function.
|
|
*
|
|
* Values are validated when they are set. If the value passed does not
|
|
* validate against the field's specification, an Error will be thrown.
|
|
*
|
|
* @param name
|
|
* (string) The name of the field whose value to set.
|
|
* @param value
|
|
* The value to set the field to.
|
|
*/
|
|
setValue: function setValue(name, value) {
|
|
if (!this.fields[name]) {
|
|
throw new Error("Attempting to set unknown field: " + name);
|
|
}
|
|
|
|
let type = this.fields[name].type;
|
|
|
|
if (!(type in this)) {
|
|
throw new Error("Unknown field type: " + type);
|
|
}
|
|
|
|
this[type].validate(value);
|
|
this.values.set(name, value);
|
|
},
|
|
|
|
/**
|
|
* Obtain the value of a named field.
|
|
*
|
|
* @param name
|
|
* (string) The name of the field to retrieve.
|
|
*/
|
|
getValue: function getValue(name) {
|
|
return this.values.get(name);
|
|
},
|
|
|
|
/**
|
|
* Validate that this instance is in conformance with the specification.
|
|
*
|
|
* This ensures all required fields are present. Field value validation
|
|
* occurs when individual fields are set.
|
|
*/
|
|
validate: function validate() {
|
|
for (let field in this.fields) {
|
|
let spec = this.fields[field];
|
|
|
|
if (!spec.optional && !(field in this.values)) {
|
|
throw new Error("Required field not defined: " + field);
|
|
}
|
|
}
|
|
},
|
|
|
|
toJSON: function toJSON() {
|
|
let fields = {};
|
|
for (let [k, v] of this.values) {
|
|
fields[k] = v;
|
|
}
|
|
|
|
return {
|
|
name: this.name,
|
|
version: this.version,
|
|
fields: fields,
|
|
};
|
|
},
|
|
};
|
|
|
|
Object.freeze(MetricsMeasurement.prototype);
|
|
|
|
|
|
/**
|
|
* Entity which provides metrics data for recording.
|
|
*
|
|
* This essentially provides an interface that different systems must implement
|
|
* to provide collected metrics data.
|
|
*
|
|
* This type consists of various collect* functions. These functions are called
|
|
* by the metrics collector at different points during the application's
|
|
* lifetime. These functions return a `MetricsCollectionResult` instance.
|
|
* This type behaves a lot like a promise. It has a `onFinished()` that can chain
|
|
* deferred events until after the result is populated.
|
|
*
|
|
* Implementations of collect* functions should call `createResult()` to create
|
|
* a new `MetricsCollectionResult` instance. They should then register
|
|
* expected measurements with this instance, define a `populate` function on
|
|
* it, then return the instance.
|
|
*
|
|
* It is important for the collect* functions to just create the empty
|
|
* `MetricsCollectionResult` and nothing more. This is to enable the callee
|
|
* to handle errors gracefully. If the collect* function were to raise, the
|
|
* callee may not receive a `MetricsCollectionResult` instance and it would not
|
|
* know what data is missing.
|
|
*
|
|
* See the documentation for `MetricsCollectionResult` for details on how
|
|
* to perform population.
|
|
*
|
|
* Receivers of created `MetricsCollectionResult` instances should wait
|
|
* until population has finished. They can do this by chaining on to the
|
|
* promise inside that instance by calling `onFinished()`.
|
|
*
|
|
* The collect* functions can return null to signify that they will never
|
|
* provide any data. This is the default implementation. An implemented
|
|
* collect* function should *never* return null. Instead, it should return
|
|
* a `MetricsCollectionResult` with expected measurements that has finished
|
|
* populating (i.e. an empty result).
|
|
*
|
|
* @param name
|
|
* (string) The name of this provider.
|
|
*/
|
|
this.MetricsProvider = function MetricsProvider(name) {
|
|
if (!name) {
|
|
throw new Error("MetricsProvider must have a name.");
|
|
}
|
|
|
|
if (typeof(name) != "string") {
|
|
throw new Error("name must be a string. Got: " + typeof(name));
|
|
}
|
|
|
|
this._log = Log4Moz.repository.getLogger("Services.Metrics.MetricsProvider");
|
|
|
|
this.name = name;
|
|
}
|
|
|
|
MetricsProvider.prototype = {
|
|
/**
|
|
* Collects constant measurements.
|
|
*
|
|
* Constant measurements are data that doesn't change during the lifetime of
|
|
* the application/process. The metrics collector only needs to call this
|
|
* once per `MetricsProvider` instance per process lifetime.
|
|
*/
|
|
collectConstantMeasurements: function collectConstantMeasurements() {
|
|
return null;
|
|
},
|
|
|
|
/**
|
|
* Create a new `MetricsCollectionResult` tied to this provider.
|
|
*/
|
|
createResult: function createResult() {
|
|
return new MetricsCollectionResult(this.name);
|
|
},
|
|
};
|
|
|
|
Object.freeze(MetricsProvider.prototype);
|
|
|
|
|
|
/**
|
|
* Holds the result of metrics collection.
|
|
*
|
|
* This is the type eventually returned by the MetricsProvider.collect*
|
|
* functions. It holds all results and any state/errors that occurred while
|
|
* collecting.
|
|
*
|
|
* This type is essentially a container for `MetricsMeasurement` instances that
|
|
* provides some smarts useful for capturing state.
|
|
*
|
|
* The first things consumers of new instances should do is define the set of
|
|
* expected measurements this result will contain via `expectMeasurement`. If
|
|
* population of this instance is aborted or times out, downstream consumers
|
|
* will know there is missing data.
|
|
*
|
|
* Next, they should define the `populate` property to a function that
|
|
* populates the instance.
|
|
*
|
|
* The `populate` function implementation should add empty `MetricsMeasurement`
|
|
* instances to the result via `addMeasurement`. Then, it should populate these
|
|
* measurements via `setValue`.
|
|
*
|
|
* It is preferred to populate via this type instead of directly on
|
|
* `MetricsMeasurement` instances so errors with data population can be
|
|
* captured and reported.
|
|
*
|
|
* Once population has finished, `finish()` must be called.
|
|
*
|
|
* @param name
|
|
* (string) The name of the provider this result came from.
|
|
*/
|
|
this.MetricsCollectionResult = function MetricsCollectionResult(name) {
|
|
if (!name || typeof(name) != "string") {
|
|
throw new Error("Must provide name argument to MetricsCollectionResult.");
|
|
}
|
|
|
|
this._log = Log4Moz.repository.getLogger("Services.Metrics.MetricsCollectionResult");
|
|
|
|
this.name = name;
|
|
|
|
this.measurements = new Map();
|
|
this.expectedMeasurements = new Set();
|
|
this.errors = [];
|
|
|
|
this.populate = function populate() {
|
|
throw new Error("populate() must be defined on MetricsCollectionResult " +
|
|
"instance.");
|
|
};
|
|
|
|
this._deferred = Promise.defer();
|
|
}
|
|
|
|
MetricsCollectionResult.prototype = {
|
|
/**
|
|
* The Set of `MetricsMeasurement` names currently missing from this result.
|
|
*/
|
|
get missingMeasurements() {
|
|
let missing = new Set();
|
|
|
|
for (let name of this.expectedMeasurements) {
|
|
if (this.measurements.has(name)) {
|
|
continue;
|
|
}
|
|
|
|
missing.add(name);
|
|
}
|
|
|
|
return missing;
|
|
},
|
|
|
|
/**
|
|
* Record that this result is expected to provide a named measurement.
|
|
*
|
|
* This function should be called ASAP on new `MetricsCollectionResult`
|
|
* instances. It defines expectations about what data should be present.
|
|
*
|
|
* @param name
|
|
* (string) The name of the measurement this result should contain.
|
|
*/
|
|
expectMeasurement: function expectMeasurement(name) {
|
|
this.expectedMeasurements.add(name);
|
|
},
|
|
|
|
/**
|
|
* Add a `MetricsMeasurement` to this result.
|
|
*/
|
|
addMeasurement: function addMeasurement(data) {
|
|
if (!(data instanceof MetricsMeasurement)) {
|
|
throw new Error("addMeasurement expects a MetricsMeasurement instance.");
|
|
}
|
|
|
|
if (!this.expectedMeasurements.has(data.name)) {
|
|
throw new Error("Not expecting this measurement: " + data.name);
|
|
}
|
|
|
|
if (this.measurements.has(data.name)) {
|
|
throw new Error("Measurement of this name already present: " + data.name);
|
|
}
|
|
|
|
this.measurements.set(data.name, data);
|
|
},
|
|
|
|
/**
|
|
* Sets the value of a field in a registered measurement instance.
|
|
*
|
|
* This is a convenience function to set a field on a measurement. If an
|
|
* error occurs, it will record that error in the errors container.
|
|
*
|
|
* Attempting to set a value on a measurement that does not exist results
|
|
* in an Error being thrown. Attempting a bad assignment on an existing
|
|
* measurement will not throw unless `rethrow` is true.
|
|
*
|
|
* @param name
|
|
* (string) The `MetricsMeasurement` on which to set the value.
|
|
* @param field
|
|
* (string) The field we are setting.
|
|
* @param value
|
|
* The value being set.
|
|
* @param rethrow
|
|
* (bool) Whether to rethrow any errors encountered.
|
|
*
|
|
* @return bool
|
|
* Whether the assignment was successful.
|
|
*/
|
|
setValue: function setValue(name, field, value, rethrow=false) {
|
|
let m = this.measurements.get(name);
|
|
if (!m) {
|
|
throw new Error("Attempting to operate on an undefined measurement: " +
|
|
name);
|
|
}
|
|
|
|
try {
|
|
m.setValue(field, value);
|
|
return true;
|
|
} catch (ex) {
|
|
this.addError(ex);
|
|
|
|
if (rethrow) {
|
|
throw ex;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Record an error that was encountered when populating this result.
|
|
*/
|
|
addError: function addError(error) {
|
|
this.errors.push(error);
|
|
},
|
|
|
|
/**
|
|
* Aggregate another MetricsCollectionResult into this one.
|
|
*
|
|
* Instances can only be aggregated together if they belong to the same
|
|
* provider (they have the same name).
|
|
*/
|
|
aggregate: function aggregate(other) {
|
|
if (!(other instanceof MetricsCollectionResult)) {
|
|
throw new Error("aggregate expects a MetricsCollectionResult instance.");
|
|
}
|
|
|
|
if (this.name != other.name) {
|
|
throw new Error("Can only aggregate MetricsCollectionResult from " +
|
|
"the same provider. " + this.name + " != " + other.name);
|
|
}
|
|
|
|
for (let name of other.expectedMeasurements) {
|
|
this.expectedMeasurements.add(name);
|
|
}
|
|
|
|
for (let [name, m] of other.measurements) {
|
|
if (this.measurements.has(name)) {
|
|
throw new Error("Incoming result has same measurement as us: " + name);
|
|
}
|
|
|
|
this.measurements.set(name, m);
|
|
}
|
|
|
|
this.errors = this.errors.concat(other.errors);
|
|
},
|
|
|
|
toJSON: function toJSON() {
|
|
let o = {
|
|
measurements: {},
|
|
missing: [],
|
|
errors: [],
|
|
};
|
|
|
|
for (let [name, value] of this.measurements) {
|
|
o.measurements[name] = value;
|
|
}
|
|
|
|
for (let missing of this.missingMeasurements) {
|
|
o.missing.push(missing);
|
|
}
|
|
|
|
for (let error of this.errors) {
|
|
if (error.message) {
|
|
o.errors.push(error.message);
|
|
} else {
|
|
o.errors.push(error);
|
|
}
|
|
}
|
|
|
|
return o;
|
|
},
|
|
|
|
/**
|
|
* Signal that population of the result has finished.
|
|
*
|
|
* This will resolve the internal promise.
|
|
*/
|
|
finish: function finish() {
|
|
this._deferred.resolve(this);
|
|
},
|
|
|
|
/**
|
|
* Chain deferred behavior until after the result has finished population.
|
|
*
|
|
* This is a wrapped around the internal promise's `then`.
|
|
*
|
|
* We can't call this "then" because the core promise library will get
|
|
* confused.
|
|
*/
|
|
onFinished: function onFinished(onFulfill, onError) {
|
|
return this._deferred.promise.then(onFulfill, onError);
|
|
},
|
|
};
|
|
|
|
Object.freeze(MetricsCollectionResult.prototype);
|
|
|