使用计数器¶

使用计数器用于报告关于给定 Web 平台功能在整个 Web 上的使用情况的统计数据。支持的功能包括

页面、文档和工作线程的 WebIDL 方法和属性（getter 和 setter 分别报告），
CSS 属性（包括不在 Web 平台中但我们感兴趣的属性），
已弃用的 DOM 操作，
以及其他内容，例如 SVG 过滤器和在隐私浏览模式下明确不支持的 API，通过自定义使用计数器。

添加新的使用计数器¶

添加新使用计数器的方法取决于您要检测的 Web 平台功能的类型。唯一不变的是，在添加或删除使用计数器后，必须运行 ./mach gen-use-counter-metrics。

（为什么这是一个手动步骤而不是构建的一部分，在实现错误 1852098 中有解释。）

WebIDL 方法和属性¶

WebIDL 方法和属性的使用计数器是通过手动编辑 UseCounters.conf 或对于工作线程，编辑 UseCountersWorker.conf，并使用 [UseCounter] 扩展属性注释 WebIDL 方法或属性来添加的。

（为什么必须在这两个地方编写是因为从绑定代码生成中生成内容并确保所有依赖项都正确被证明相当困难）

然后运行 ./mach gen-use-counter-metrics 并像往常一样构建。

CSS 属性¶

CSS 属性的使用计数器会自动为 Gecko 支持的每个属性生成。

要为 Gecko 不支持的 CSS 属性添加使用计数器，请将其添加到 counted_unknown_properties.py 中。

然后运行 ./mach gen-use-counter-metrics 并像往常一样构建。

已弃用的 DOM 操作¶

已弃用的 DOM 操作的使用计数器在 nsDeprecatedOperationList.h 中声明。要为已弃用的 DOM 操作添加使用计数器，您需要添加 DEPRECATED_OPERATION(DeprecationReference) 宏的调用。提供的参数必须与添加到 IDL 文件中的弃用说明具有相同的值。

请参阅错误 1860635 以了解已弃用操作的示例。

然后运行 ./mach gen-use-counter-metrics 并像往常一样构建。

自定义使用计数器¶

自定义使用计数器用于计算每个页面、每个文档或每个工作线程对无法通过 WebIDL 注释直接处理的 Web 平台功能的使用情况。

例如，特定 SVG 过滤器的使用不是 WebIDL 方法或属性，但仍然是我们感兴趣的 Web 平台方面。

要添加自定义使用计数器，请按照文件中的说明，在 UseCounters.conf 或对于工作线程，在 UseCountersWorker.conf 中定义它。大体上，您将编写类似于 custom feBlend uses the feBlend SVG filter 的一行。

然后，通过像往常一样运行构建，将在 enum class UseCounter 中为您的使用计数器生成一个枚举，您应该在使用时将其传递给 Document::SetUseCounter()。 Document::SetUseCounter() 非常廉价，因此不要害怕每次使用该功能时都调用它。

注意适当地编写描述。它将附加到“是否文档”或“是否共享工作线程”，因此只需编写结尾部分。

处理器脚本¶

定义文件在构建期间被处理以生成由拥有要跟踪的功能的 Web 平台组件（例如 DOM）包含的 C++ 头文件。

定义文件也在 ./mach gen-use-counter-metrics 期间被处理以生成 use_counter_metrics.yaml，该文件生成记录和报告使用计数器数据所需的 Glean 指标。

gen-usecounters.py¶

此脚本由构建系统调用以生成

WebIDL 的 UseCounterList.h 头文件，来自定义文件。
WebIDL 的 UseCounterWorkerList.h 头文件，来自定义文件。

usecounters.py¶

包含用于解析和转换使用计数器定义文件的方法，以及输出 Glean 使用计数器指标定义的机制。

数据审查¶

使用计数器数据收集的概念（即 Web 平台功能，其使用次数（页面、文档、各种类型的worker或其他广泛类别的 Web 平台 API 表面）由数据收集机制（如 Glean）记录和报告）已获准在错误 1852098 中使用 Gecko 和 Glean 的所有产品中选择性收集。

因此，如果您正在为 WebIDL 方法或属性、已弃用操作或 CSS 属性添加新的使用计数器数据收集：您几乎肯定不需要数据收集审查。

如果您正在添加自定义使用计数器，则可能需要数据收集审查。是否需要审查的标准是您添加的自定义使用计数器是否可以归入总体数据收集审查请求。例如：SVG 过滤器的自定义使用计数器？显然是正在计数的 Web 平台功能。仅在您访问社交媒体网站时递增的自定义使用计数器？似乎不包括在内，不是吗？

如有疑问，请在 Matrix 上的 #data-stewards 频道中询问。

数据¶

截至 Firefox 121，使用计数器使用 Glean 作为“use-counters” ping 上的 counter 指标进行收集。它们位于各种 use.counter.X 指标类别中，您可以在 Glean 词典上浏览。词典还包含有关如何查看数据的信息。

解读数据¶

单独的使用计数器用处不大，因为它仅仅是 Web 平台的某个部分在多少（页面、文档、特定类型的worker或其他 Web 平台 API 表面）上被使用的计数。

知道在所有 Firefox 中遇到某个功能的次数为 0 将很有用。（如果您想删除某些内容）。知道某个功能遇到的次数超过 0 将很有用。（如果您想反对删除某些内容）。

但是，例如，使用 Web 平台功能的页面的任何其他数量仅在与查看的总页面数相关的上下文中才有用。

因此，每个使用计数器在其描述中都有另一个计数器的名称——分母——将使用计数器转换为使用率。

以页面为例，知道 CSS 属性 overflow 在 1504 个页面上使用……很好。我想。但是，如果您对 use.counters.top_level_content_documents_destroyed 求和以发现仅加载了 1506 个页面？这是一个我们可以利用的数字。我们可以按流行度对 MDN 搜索结果进行排序。我们可以优先考虑 Gecko 中的性能工作，重点关注最常遇到的功能。我们可以查看一段时间内的流行度，并了解何时可以弃用和删除该功能。

这就是为什么您更有可能遇到表示为使用率的使用计数器数据的原因。