WebAPI/ResourceStats

Objective

ResourceStats API provides a generic interface to access resource statistics of Firefox OS devices. It also provides an interface for resource control.

Implementation

WebIDl Definition

ResourceStats.webidl

[JSImplementation="@mozilla.org/networkStatsData;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"]
interface NetworkStatsData
{
  readonly attribute unsigned long long   receivedBytes;
  readonly attribute unsigned long long   sentBytes;
  readonly attribute DOMTimeStamp         timestamp;      // timestamp of the record
};

[JSImplementation="@mozilla.org/powerStatsData;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"]
interface PowerStatsData
{
  readonly attribute unsigned long long   consumedPower;  // unit: mW
  readonly attribute DOMTimeStamp         timestamp;      // timestamp of the record
};

[JSImplementation="@mozilla.org/resourceStats;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"]
interface ResourceStats
{
  /**
   * Type of statistics/
   */
  readonly attribute ResourceType   type;

  /**
   * The component that statistics belongs to.
   * If null, sum of all components' statistics are returned.
   */
  readonly attribute DOMString?     component;

  /**
   * |serviceType| specifies the system service.
   * |manifestURL| specifies the manifestURL of an application.
   *
   * If both |systemService| and |manifestURL| are null, then getStats()
   * returns a system-wide resource statistics.
   *
   * If |manifestURL| is not null, then getStats() returns statistics of
   * that application.
   *
   * If |serviceType| is not null, then getStats returns statistics of
   * that system service.
   *
   * If both |systemService| and |manifestURL| are specified, then the returned
   * statistics indicates the resources that the system service consumed for
   * the application.
   */
  readonly attribute SystemService? serviceType;
  readonly attribute DOMString?     manifestURL;

  /**
   * Statistics, one element per day
   */
  sequence<(NetworkStatsData or PowerStatsData)> getStats();

  /**
   * Date range
   */
  readonly attribute DOMTimeStamp   start;  // start timestamp
  readonly attribute DOMTimeStamp   end;    // end timestamp
};

ResourceStatsManager.webidl

/**
 * Supported resource statistics
 */
enum ResourceType {
  "network",
 "power"
};

/**
 * List of system services supporting resource statistics
 */
enum SystemService {
  "ota",
  "tethering"
};

dictionary ResourceStatsOptions
{
  /**
   * |component| specifies which component's resource usage will be returned.
   * If null or undefined, sum of all components' usage is returned.
   *
   * |component| is expressed in "<component>:<id>", where <component> is the
   * name of the component and <id> is used to identify different entities.
   *
   * The <id> field is mainly used in specifying the identity of different SIMs
   * when quering mobile network usage, e.g. "mobile:<iccid>".
   *
   * Quering statistics of other components should specify the |component| to
   *  "<component>:0", such as "cpu:0" or "wifi:0".
   */
  DOMString? component = null;

  /**
   * |manifestURL| specifies the manifestURL of an application.
   * |systemService| specifies the system service.
   *
   * If both |systemService| and |manifestURL| are null or undefined, then a
   * system-wide resource statistics is returned.
   *
   * If |manifestURL| is specified, then the resource statistics of the
   * specified application is returned.
   *
   * If |systemService| is specified, then the resource statistics of the
   * specified system service is returned.
   *
   * If |systemService| and |manifestURL| are both specified, then the return
   * statistics indicates the resources that the system service consumed for
   * the application.
   */
  SystemService? serviceType = null;
  DOMString? manifestURL = null;
};

dictionary ResourceStatsAlarmOptions
{
  /**
   * |startTime| indicates the start time of counting the resource usage.
   *
   * |data| is used to reflect in the alarm object when the alarm is triggered.
   * |data| should be copied using the structured clone algorithm.
   */
  DOMTimeStamp      startTime;  // time in milliseconds since Epoch
  any               data;
};

[JSImplementation="@mozilla.org/resourceStatsAlarm;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"]
interface ResourceStatsAlarm
{
  readonly attribute unsigned long          alarmId;
  readonly attribute ResourceType           type;
  readonly attribute DOMString              component;
  readonly attribute SystemService          serviceType;
  readonly attribute DOMString              manifestURL;
  readonly attribute unsigned long long     threshold;
  readonly attribute any                    data;
};

[Constructor(ResourceType type), JSImplementation="@mozilla.org/resourceStatsManager;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"]
interface ResourceStatsManager
{
  /**
   * Query resource statistics.
   *
   * |statsOptions| specifies the detail of statistics of interest.
   *
   * |start| and |end| specifies the time range of interest, both included.
   * If |start| is null or undefined, retrieve the stats since measurements.
   * If |end| is null or undefined. retrieve the stats until the current time.
   *
   * If success, the fulfillment value is an array of ResourceStats object.
   */
  Promise getStats(optional ResourceStatsOptions statsOptions,
                   optional DOMTimeStamp? start = null,
                  optional DOMTimeStamp? end = null);

  /**
   * Clear resource statistics stored in database.
   *
   * |statsOptions| specifies the detail of statistics to delete.
   *
   * |start| and |end| specifies the time range of interest, both included.
   * If |start| is null or undefined, delete the stats since measurements.
   * If |end| is null or undefined. delete the stats until the current time.
   */
  Promise clearStats(optional ResourceStatsOptions statsOptions,
                     optional DOMTimeStamp? start = null,
                     optional DOMTimeStamp? end = null);

  /**
   * Clear all resource statistics stored in database.
   */
  Promise clearAllStats();

  /**
   * Install an alarm to monitor resource usage.
   *
   * The |threshold| is an object specified the limit of resource usage. When
   * resource usage reaches the threshold, a "resourceStats-alarm" system
   * message is sent to the application.
   *
   * |statsOptions| specifies the detail of statistics of interest.
   *
   * |alarmOptions| is a ResourceStatsAlarmOptions object.
   *
   * If success, the fulfillment value is an alarm ID.
   */
  Promise addAlarm(unsigned long long threshold,
                   optional ResourceStatsOptions statsOptions,
                   optional ResourceStatsAlarmOptions alarmOptions);

  /**
   * Obtain alarms.
   *
   * If |statsOptions| is provided, then only the alarms monitoring that
   * resource are returned. Otherwise, all alarms set for this resource type
   * is returned.
   *
   * If success, the fulfillment value is an array of ResourceStatsAlarm.
   */
  Promise getAlarms(optional ResourceStatsOptions statsOptions);

  /**
   * Remove the specified alarm.
   *
   * |alarmId| specifies the alarm to be removed.
   */
  Promise removeAlarm(unsigned long alarmId);

  /**
   * Remove all alarms.
   */
  Promise removeAllAlarms();

  /**
   * Enumerate components that have stored statistics in database.
   *
   * If success, the fulfillment value is an array of DOMString.
   */
  Promise getAvailableComponents();

  /**
   * Return supporting resource statistics, i.e. ["Network", "Power"]
   *
   * This should be specified as static attribute after Bug 863952 is resolved.
   */
  [Cached, Pure]
  readonly attribute sequence<DOMString> resourceTypes;

  /**
   * Time in milliseconds between statistics stored in database.
   *
   * This should be specified as static attribute after Bug 863952 is resolved.
   */
  readonly attribute unsigned long sampleRate;

  /**
   * Time in milliseconds recorded by the API until present time. All
   * statistics older than maxStorageAge from now are deleted.
   *
   * This should be specified as static attribute after Bug 863952 is resolved.
   */
  readonly attribute unsigned long long maxStorageAge;
};

Bugs

bug 951976: API for Resource Statistics