添加新的遥测探针¶
在 Firefox 中，遥测系统会收集 Firefox 性能、硬件、使用情况和自定义设置等各种指标，并将其提交给 Mozilla。本文概述了添加任何新的遥测数据收集所需的信息。
重要
Firefox 中的每个新数据收集都需要来自数据收集同行的 数据收集审查。只需为其中一位数据同行设置 feedback? 标记即可。他们会尝试在工作日内回复。
你的目标是什么？¶
我们提供了各种 数据收集工具，每个工具都满足不同的需求。在深入了解技术细节之前，最好先退一步，考虑一下你需要实现的目标。
你的目标可能是回答诸如“有多少人使用功能 X？”或“服务 Y 的错误率是多少？”之类产品问题。你也可以专注于回答工程问题，例如“哪些 Web 功能使用最多？”或“引擎 Z 的性能如何？”。
由此，你应该问的问题是
哪些是最少的数据可以回答你的问题？
你需要从多少人那里获取这些数据？
预发布渠道的数据是否足够？
这也会影响 数据收集审查，该审查需要一个关于如何使用数据的计划。所有新的数据收集都需要进行数据收集审查。
数据收集级别¶
我们的大部分数据收集都属于以下两个级别之一：发布和预发布。
发布数据在所有渠道上默认记录，用户需要明确选择退出才能禁用它。这对我们可以收集的数据有 更严格的限制。“大多数”用户会提交这些数据。
预发布数据不会在发布版上记录，但会在我们的预发布渠道（Beta 和 Nightly）上默认收集，因此可能会存在偏差。
这些级别涵盖了 Firefox 隐私声明中所述内容。对于其他需求，可能存在需要用户明确选择加入并显示收集哪些数据的自定义机制。
丰富数据 & 聚合数据¶
对于数据的记录和传输，我们提供了各种数据类型。我们可以将这些数据类型分为两大类。
聚合数据在客户端进行聚合，发送、处理和分析的成本低廉。例如，这可能是标签打开次数的简单计数，或者显示在标签之间切换所需时间的直方图。这应该是你的默认选择，并且在我们的分析工具中得到了很好的支持。
丰富数据用于无法从聚合数据中获得答案的问题。当我们发送更详细的数据时，我们可以例如看到特定的 UI 交互何时发生以及在什么上下文中发生。
作为一般规则，你可以根据你的目标来确定数据类型的选择，如下所示
目标 |
收集类型 |
实现 |
|---|---|---|
持续监控 健康跟踪 KPI 影响 |
聚合数据 |
直方图 标量 环境数据 |
详细的用户行为 漏斗分析 诊断 |
丰富数据 |
事件遥测 详细的自定义 ping 日志 崩溃数据 |
聚合数据¶
标量允许收集简单值，例如计数、布尔值和字符串。
直方图允许收集多个不同的值，但将它们聚合到一定数量的桶中。每个桶都有一个值范围和一个我们记录了多少值的计数。
标量和直方图都允许通过键进行记录。这允许更灵活的两级数据收集。
我们还收集 环境数据。这主要由捕获 Firefox 会话“工作环境”的标量值组成，包括例如硬件、操作系统、附加组件和一些设置方面的数据。任何属于“工作环境”的一部分或需要拆分 子会话 的数据都应该包含在其中。
丰富数据¶
聚合数据可以告诉你某些事情发生了，但通常缺乏关于究竟发生了什么的细节。当需要更多细节时，我们可以使用其他工具收集效率较低的数据。这通常意味着由于成本和性能方面的考虑，我们无法为所有用户启用数据收集。
有多种机制可以收集丰富数据
堆栈收集有助于例如诊断挂起。堆栈数据记录到 chrome 挂起和线程挂起统计信息中。为了诊断很少使用的代码是从哪里调用的，你可以使用堆栈捕获。
事件遥测 提供了一种记录何时以及发生了什么的方法。这例如可以实现使用情况的漏斗分析。
自定义 ping 用于其他现有数据收集无法满足你的需求时。提交自定义 ping 使你能够提交自己的 JSON 包，该包将被传递到遥测服务器。但是，这会让你无法访问现有的工具，并使你的数据更难与其他来源合并。
设置 & 构建¶
每个 Firefox 构建都启用了遥测。没有自定义构建标志的本地开发人员构建将记录所有遥测数据，但不会发送出去。
添加任何新的标量、直方图或事件时，都需要构建 Firefox。即使代码更改仅限于 JavaScript，目前也不支持工件构建。
通常，你不需要发送数据来添加新的遥测。在极少数情况下你需要这样做，你需要在你的 .mozconfig 中添加以下内容
MOZ_TELEMETRY_REPORTING=1
MOZILLA_OFFICIAL=1
测试¶
本地确认¶
你的第一步始终应该是本地确认你的新数据收集。
about:telemetry 页面允许查看你在过去 60 天内提交给遥测的任何数据，无论是在现有的 ping 中还是在新自定义 ping 中。你可以在左上角选择要显示的 ping。
如果你需要确认 ping 何时或是否正在发送，则可以在本地运行 gzipServer 的实例。它大致模拟了官方遥测服务器的响应方式，并将所有接收到的 ping 保存到磁盘以供检查。
测试覆盖率¶
任何需要根据其进行决策的数据收集都需要有测试覆盖率。使用 JS，你可以访问数据收集的记录值。你可以使用以下函数
对于直方图，getSnapshotForHistograms() 或 getSnapshotForKeyedHistograms()
可选地，直方图对象具有 snapshot() 方法。
对于事件，snapshotEvents()
如果你需要测试 ping 是否已正确传递到遥测，则可以使用 TelemetryArchiveTesting。
验证¶
虽然确认数据收集在你的机器上是否有效很重要，但 Firefox 用户群体非常多样化。在根据任何新数据做出决策之前，应对其进行验证。这可能采取各种形式。
对于使用现有遥测数据类型的新数据收集，传输机制已经过测试。验证传入的值就足够了。这可以通过 Redash 或通过 自定义分析 来实现。
对于新的自定义 ping，你需要检查模式验证结果，以及内容是否有效。
获取帮助¶
你可以在 telemetry.mozilla.org 上找到所有重要的遥测资源。
遥测团队随时准备帮助解决任何问题。你可以通过以下方式联系我们
Matrix 在 #telemetry:mozilla.org
Slack 在 #data-help
Bugzilla 上为 其中一位同行设置标记或向我们发送电子邮件