更新数据采集

Firefox 持续从不同的远程源获取数据（例如：设置、系统附加组件等）。为了获得关于这些更新源的采用率的一致洞察，我们的客户端可以使用统一的遥测助手来报告其更新状态。

下面描述的助手报告预定义的更新状态，这最终提供了一种统一的方式来获取

• 客户端成功更新的比例；

• 其随时间的演变；

• 错误原因的分布。

注意

更新源的示例：远程设置、附加组件更新、附加组件、gfx 和插件黑名单、证书吊销、证书固定、系统附加组件交付…

更新状态的示例：最新、成功、网络错误、服务器错误、签名错误、服务器回退、未知错误…

每次调用 UptakeTelemetry 助手都可能发送一个遥测事件。由于事件开销较大，我们采取了一些措施来避免这些数据泛滥，从而压垮 Mozilla 系统。我们始终在非发布通道上发送事件。在发布通道上，我们仅从 1% 的客户端发送事件。

用法

const { UptakeTelemetry } = ChromeUtils.import("resource://services-common/uptake-telemetry.js", {});

UptakeTelemetry.report(component, status, { source });

• component，一个string，用于标识调用组件（例如"remotesettings"、"normandy"）。任意组件必须在遥测事件定义文件中预先声明。

• source，一个string，用于区分组件中正在提取或更新的内容（例如"blocklists/addons"、"recipes/33"）

• status，以下状态常量之一

  • UptakeTelemetry.STATUS.UP_TO_DATE：本地内容已与远程内容保持最新。

  • UptakeTelemetry.STATUS.SUCCESS：本地内容已成功更新。

  • UptakeTelemetry.STATUS.BACKOFF：远程服务器要求客户端回退。

  • UptakeTelemetry.STATUS.PREF_DISABLED：用户偏好设置中已禁用更新。

  • UptakeTelemetry.STATUS.PARSE_ERROR：解析服务器响应失败。

  • UptakeTelemetry.STATUS.CONTENT_ERROR：服务器响应具有意外内容。

  • UptakeTelemetry.STATUS.CORRUPTION_ERROR：与本地数据损坏相关的错误。

  • UptakeTelemetry.STATUS.SIGNATURE_ERROR：基于差异的同步后的签名验证失败。

  • UptakeTelemetry.STATUS.SIGNATURE_RETRY_ERROR：完整获取后的签名验证失败。

  • UptakeTelemetry.STATUS.CONFLICT_ERROR：某些远程更改与本地更改冲突。

  • UptakeTelemetry.STATUS.SYNC_ERROR：远程更改的同步失败。

  • UptakeTelemetry.STATUS.APPLY_ERROR：本地应用更改失败。

  • UptakeTelemetry.STATUS.SERVER_ERROR：服务器未能响应。

  • UptakeTelemetry.STATUS.CERTIFICATE_ERROR：服务器证书验证失败。

  • UptakeTelemetry.STATUS.DOWNLOAD_ERROR：无法完全检索数据。

  • UptakeTelemetry.STATUS.TIMEOUT_ERROR：服务器响应超时。

  • UptakeTelemetry.STATUS.NETWORK_ERROR：与服务器的通信失败。

  • UptakeTelemetry.STATUS.NETWORK_OFFLINE_ERROR：网络不可用。

  • UptakeTelemetry.STATUS.CLEANUP_ERROR：临时文件的清理失败。

  • UptakeTelemetry.STATUS.SHUTDOWN_ERROR：关机期间发生的错误。

  • UptakeTelemetry.STATUS.UNKNOWN_ERROR：未分类的错误。

  • UptakeTelemetry.STATUS.CUSTOM_1_ERROR：此更新源特有的错误 #1。

  • UptakeTelemetry.STATUS.CUSTOM_2_ERROR：此更新源特有的错误 #2。

  • UptakeTelemetry.STATUS.CUSTOM_3_ERROR：此更新源特有的错误 #3。

  • UptakeTelemetry.STATUS.CUSTOM_4_ERROR：此更新源特有的错误 #4。

  • UptakeTelemetry.STATUS.CUSTOM_5_ERROR：此更新源特有的错误 #5。

示例

const COMPONENT = "normandy";
const UPDATE_SOURCE = "update-monitoring";

let status;
try {
  const data = await fetch(uri);
  status = UptakeTelemetry.STATUS.SUCCESS;
} catch (e) {
  status = /NetworkError/.test(e) ?
              UptakeTelemetry.STATUS.NETWORK_ERROR :
              UptakeTelemetry.STATUS.SERVER_ERROR ;
}
UptakeTelemetry.report(COMPONENT, status, { source: UPDATE_SOURCE });

其他事件信息

使用遥测事件 API 发送的事件可以包含其他信息。更新数据采集允许您通过将它们添加到options参数中，将以下额外字段添加到事件中

• trigger：一个标签，用于区分触发远程内容轮询/获取的操作（例如"broadcast"、"timer"、"forced"、"manual"）

• age：以秒为单位的提取数据的年龄（即发布时间和提取时间之间的差异）。

• duration：同步过程的持续时间（毫秒）。

UptakeTelemetry.report(component, status, { source, trigger: "timer", age: 138 });

请记住，在发布通道上对事件进行采样。那些不会生成事件的更新数据采集调用将忽略这些额外字段。

用例

以下远程数据源已使用此统一直方图。

• 远程设置更改监控

• 附加组件黑名单

• gfx 黑名单

• 插件黑名单

• 证书吊销

• 证书固定

• Normandy Recipe 客户端

显然，目标是最终融合并避免用于测量远程内容采用率的临时遥测探测。一些值得注意的潜在用例是

• nsUpdateService

• mozapps 扩展更新