dom/docs/use-counters.rst

   1 ============
   2 Use Counters
   3 ============
   4
   5 Use counters are used to report statistics on how much a given web platform feature is used across the Web.
   6 Supported features include:
   7
   8 * WebIDL methods and attributes (getters and setters are reported separately) for pages, documents, and workers,
   9 * CSS properties (including properties that aren't in the web platform, but we're interested in),
  10 * Deprecated DOM operations,
  11 * Other things like SVG filters and APIs specifically unsupported in Private Browsing Mode,
  12   via custom use counters.
  13
  14 Adding a new Use Counter
  15 ========================
  16 How you add a new use counter is different depending on what kind of web platform feature you're instrumenting.
  17 The one constant is that you must run ``./mach gen-use-counter-metrics``
  18 after adding or removing a use counter.
  19
  20 (Why this is a manual step and not part of the build is explained in
  21 `the implementation bug 1852098 <https://bugzilla.mozilla.org/show_bug.cgi?id=1852098#c11>`_.)
  22
  23 WebIDL Methods and Attributes
  24 -----------------------------
  25 Use counters for WebIDL Methods and Attributes are added manually by editing
  26 :searchfox:`UseCounters.conf <dom/base/UseCounters.conf>` or, for workers,
  27 :searchfox:`UseCountersWorker.conf <dom/base/UseCountersWorker.conf>`, and
  28 by annotating the WebIDL Method or Attribute with the ``[UseCounter]``
  29 extended attribute.
  30
  31 (Why you must write this in two places is because generating things from
  32 bindings codegen and ensuring all the dependencies were correct proved to be
  33 rather difficult)
  34
  35 Then run ``./mach gen-use-counter-metrics`` and build as normal.
  36
  37 CSS Properties
  38 --------------
  39 Use counters for CSS properties are automatically generated for every property Gecko supports.
  40
  41 To add a use counter for a CSS property that isn't supported by Gecko,
  42 add it to :searchfox:`counted_unknown_properties.py <servo/components/style/properties/counted_unknown_properties.py>`.
  43
  44 Then run ``./mach gen-use-counter-metrics`` and build as normal.
  45
  46 Deprecated DOM operations
  47 -------------------------
  48 Use counters for deprecated DOM operations are declared in
  49 :searchfox:`nsDeprecatedOperationList.h <dom/base/nsDeprecatedOperationList.h>`.
  50 To add a use counter for a deprecated DOM operation, you'll add an invocation of the
  51 ``DEPRECATED_OPERATION(DeprecationReference)`` macro.
  52 The provided parameter must have the same value of the deprecation note added to the *IDL* file.
  53
  54 See `bug 1860635 <https://bugzilla.mozilla.org/show_bug.cgi?id=1860635>`_ for a sample
  55 deprecated operation.
  56
  57 Then run ``./mach gen-use-counter-metrics`` and build as normal.
  58
  59 Custom use counters
  60 -------------------
  61 Custom use counters are for counting per-page, per-document, or per-worker
  62 uses of web platform features that can't be handled directly through WebIDL annotation.
  63
  64 For example, the use of specific SVG filters isn't a WebIDL method or attribute,
  65 but was still an aspect of the web platform of interest.
  66
  67 To add a custom use counter, define it in
  68 :searchfox:`UseCounters.conf <dom/base/UseCounters.conf>` or, for workers,
  69 :searchfox:`UseCountersWorker.conf <dom/base/UseCountersWorker.conf>`
  70 by following the instructions in the file.
  71 Broadly, you'll be writing a line like ``custom feBlend uses the feBlend SVG filter``.
  72
  73 Then, by running the build as normal, an enum in ``enum class UseCounter``
  74 will be generated for your use counter, which you should pass to
  75 ``Document::SetUseCounter()`` when it's used.
  76 ``Document::SetUseCounter()`` is very cheap,
  77 so do not be afraid to call it every time the feature is used.
  78
  79 Take care to craft the description appropriately.
  80 It will be appended to "Whether a document " or "Whether a shared worker ",
  81 so write only the ending.
  82
  83
  84 The processor scripts
  85 =====================
  86 The definition files are processed during the build to generate C++ headers
  87 included by web platform components (e.g. DOM) that own the features to be tracked.
  88
  89 The definition files are also processed during ``./mach gen-use-counter-metrics``
  90 to generate :searchfox:`use_counter_metrics.yaml <dom/base/use_counter_metrics.yaml>`
  91 which generates the necessary Glean metrics for recording and reporting use counter data.
  92
  93 gen-usecounters.py
  94 ------------------
  95 This script is called by the build system to generate:
  96
  97 - the ``UseCounterList.h`` header for the WebIDL, out of the definition files.
  98 - the ``UseCounterWorkerList.h`` header for the WebIDL, out of the definition files.
  99
 100 usecounters.py
 101 --------------
 102 Contains methods for parsing and transforming use counter definition files,
 103 as well as the mechanism that outputs the Glean use counter metrics definitions.
 104
 105 Data Review
 106 ===========
 107 The concept of a Use Counter data collection
 108 (being a web platform feature which has the number of pages, documents, workers
 109 (of various types), or other broad category of web platform API surfaces that
 110 *use* it recorded and reported by a data collection mechanism (like Glean))
 111 was approved for opt-out collection in all products using Gecko and Glean in
 112 `bug 1852098 <https://bugzilla.mozilla.org/show_bug.cgi?id=1852098>`_.
 113
 114 As a result,
 115 if you are adding new use counter data collections for WebIDL methods or attributes,
 116 deprecated operations, or CSS properties:
 117 you almost certainly don't need a data collection review.
 118
 119 If you are adding a custom use counter, you might need a data collection review.
 120 The criteria for whether you do or not is whether the custom use counter you're adding
 121 can fall under
 122 `the over-arching data collection review request <https://bugzilla.mozilla.org/show_bug.cgi?id=1852098>`_.
 123 For example: a custom use counter for an SVG filter? Clearly a web platform feature being counted.
 124 A custom use counter that solely increments when you visit a social media website?
 125 Doesn't seem like it'd be covered, no.
 126
 127 If unsure, please ask on
 128 `the #data-stewards channel on Matrix <https://chat.mozilla.org/#/room/#data-stewards:mozilla.org>`_.
 129
 130 The Data
 131 ========
 132 Use Counters are, as of Firefox 121, collected using Glean as
 133 ``counter`` metrics on the "use-counters" ping.
 134 They are in a variety of metrics categories of ``use.counter.X``
 135 which you can browse on
 136 `the Glean Dictionary <https://dictionary.telemetry.mozilla.org/apps/firefox_desktop?page=1&search=use.counter>`_.
 137 The dictionary also contains information about how to view the data.
 138
 139 Interpreting the data
 140 ---------------------
 141 A use counter on its own is minimally useful, as it is solely a count of how many
 142 (pages, documents, workers of a specific type, other web platform API surfaces)
 143 a given part of the web platform was used on.
 144
 145 Knowing a feature was encountered ``0`` times across all of Firefox would be useful to know.
 146 (If you wanted to remove something).
 147 Knowing a feature was encountered *more than* ``0`` times would be useful.
 148 (If you wanted to argue against removing something).
 149
 150 But any other number of, say, pages using a web platform feature is only useful
 151 in context with how many total pages were viewed.
 152
 153 Thus, each use counter has in its description a name of another counter
 154 -- a denominator -- to convert the use counter into a usage rate.
 155
 156 Using pages as an example, knowing the CSS property ``overflow``
 157 is used on ``1504`` pages is... nice. I guess.
 158 But if you sum up ``use.counters.top_level_content_documents_destroyed``
 159 to find that there were only ``1506`` pages loaded?
 160 That's a figure we can do something with.
 161 We can order MDN search results by popularity.
 162 We can prioritize performance efforts in Gecko to focus on the most-encountered features.
 163 We can view the popularity over time and see when we expect we'll be able to deprecate and remove the feature.
 164
 165 This is why you'll more likely encounter use counter data expressed as usage rates.