use-counters.rst (7689B)
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.