gecko-dev/toolkit/components/perfmonitoring/nsIPerformanceStats.idl

/* -*- indent-tabs-mode: nil; js-indent-level: 2 -*-*/
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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/. */

#include "nsISupports.idl"
#include "nsIArray.idl"
#include "nsIDOMWindow.idl"

/**
 * Mechanisms for querying the current process about performance
 * information.
 *
 * JavaScript clients should rather use PerformanceStats.jsm.
 */

/**
 * Snapshot of the performance of a component, e.g. an add-on, a web
 * page, system built-ins, a module or the entire process itself.
 *
 * All values are monotonic and are updated only when
 * `nsIPerformanceStatsService.isStopwatchActive` is `true`.
 */
[scriptable, uuid(89440555-dd81-4a22-8747-049bcf0ab586)]
interface nsIPerformanceStats: nsISupports {
  /**
   * An identifier unique to the component.
   *
   * This identifier is somewhat human-readable to aid with debugging,
   * but clients should not rely upon the format.
   */
  readonly attribute AString groupId;

  /**
   * If this component is part of a larger component, the larger
   * component. Otherwise, null.
   *
   * As of this writing, there can be at most two levels of components:
   * - compartments (a single module, iframe, etc.);
   * - groups (an entire add-on, an entire webpage, etc.).
   */
  readonly attribute AString parentId;

  /**
   * The name of the component:
   * - for the process itself, "<process>";
   * - for platform code, "<platform>";
   * - for an add-on, the identifier of the addon (e.g. "myaddon@foo.bar");
   * - for a webpage, the url of the page.
   */
  readonly attribute AString name;

  /**
   * If the component is an add-on, the ID of the addon,
   * otherwise an empty string.
   */
  readonly attribute AString addonId;

  /**
   * If the component is code executed in a window, the ID of the topmost
   * outer window (i.e. the tab), otherwise 0.
   */
  readonly attribute uint64_t windowId;

  /**
   * If the component is code executed in a window, the title of the topmost
   * window (i.e. the tab), otherwise an empty string.
   */
  readonly attribute AString title;

  /**
   * Total amount of time spent executing code in this group, in
   * microseconds.
   */
  readonly attribute unsigned long long totalUserTime;
  readonly attribute unsigned long long totalSystemTime;
  readonly attribute unsigned long long totalCPOWTime;

  /**
   * Total number of times code execution entered this group,
   * since process launch. This may be greater than the number
   * of times we have entered the event loop.
   */
  readonly attribute unsigned long long ticks;

  /**
   * `true` if this component is executed with system privileges
   * (e.g. the platform itself or an add-on), `false` otherwise
   * (e.g. webpages).
   */
  readonly attribute bool isSystem;

  /**
   * The process running this group.
   */
  readonly attribute unsigned long long processId;

  /**
   * Jank indicator.
   *
   * durations[i] == number of times execution of this group
   * lasted at lest 2^i ms.
   */
  void getDurations([optional] out unsigned long aCount,
                    [retval, array, size_is(aCount)]out unsigned long long aNumberOfOccurrences);
};

/**
 * A snapshot of the performance data of the process.
 */
[scriptable, uuid(2e0c50e2-3aff-4cc8-88a6-c0dc200da8fc)]
interface nsIPerformanceSnapshot: nsISupports {
  /**
   * Data on all individual components.
   */
  nsIArray getComponentsData();

  /**
   * Information on the process itself.
   *
   * This contains the total amount of time spent executing JS code,
   * the total amount of time spent waiting for system calls while
   * executing JS code, the total amount of time performing blocking
   * inter-process calls, etc.
   */
  nsIPerformanceStats getProcessData();
};

[scriptable, builtinclass, uuid(60973d54-13e2-455c-a3c6-84dea5dfc8b9)]
interface nsIPerformanceStatsService : nsISupports {
  /**
   * `true` if we should monitor CPOW, `false` otherwise.
   */
  [implicit_jscontext] attribute bool isMonitoringCPOW;

  /**
   * `true` if we should monitor jank, `false` otherwise.
   */
  [implicit_jscontext] attribute bool isMonitoringJank;

  /**
   * `true` if all compartments need to be monitored individually,
   * `false` if only performance groups (i.e. entire add-ons, entire
   * webpages, etc.) need to be monitored.
   */
  [implicit_jscontext] attribute bool isMonitoringPerCompartment;

  /**
   * Capture a snapshot of the performance data.
   */
  [implicit_jscontext] nsIPerformanceSnapshot getSnapshot();
};

%{C++
#define NS_TOOLKIT_PERFORMANCESTATSSERVICE_CID {0xfd7435d4, 0x9ec4, 0x4699, \
      {0xad, 0xd4, 0x1b, 0xe8, 0x3d, 0xd6, 0x8e, 0xf3} }
#define NS_TOOLKIT_PERFORMANCESTATSSERVICE_CONTRACTID "@mozilla.org/toolkit/performance-stats-service;1"
%}