运行时指标定义子系统：JOG

对不起

为什么叫 JOG？因为它与……运行……时间有关。

由于各种原因（从实现简单到性能），注册指标的常规机制发生在编译时。但是，这并不支持以下用例

  • 工件构建（其中仅在构建时重新打包 Firefox 桌面版 JavaScript，因此没有编译环境）

  • 动态遥测（一种理论上用于在不发布代码的情况下检测 Firefox 桌面的系统）

  • Web 扩展（或者至少是那些无法或不会使用 Glean JS SDK 的扩展）

因此，我们需要一个支持运行时注册指标的子系统。我们称之为 JOG，它是在 bug 1698184 中实现的。

仅限 JavaScript

C++ 和 Rust 中的指标由标识符标识，我们无法在运行时交换这些标识符。因此，为了使指标更改对 C++ 或 Rust 中检测到的系统可见，您必须进行编译。

另一方面，对于 JavaScript，我们按需提供实例。它不仅支持推动此项目的特定用例，而且是 Firefox 桌面版中唯一可以从运行时指标定义中受益的环境。

设计

原始设计是在 bug 1662863 中完成的。从那时起，事情大多只是得到了改进。

架构

我们将尽可能多的子系统隔离到位于 toolkit/components/glean/bindings/jog/ 中的 jog 模块中。这包括指标构造工厂和指标实例及其名称和 ID 的存储。

不幸的是，为了使指标实例可以通过 FFI 访问，由 jog crate 创建的 Rust 指标实例存储在 fog crate 中。

说到 FFI，jog crate 正在使用 cbindgen 以便于 C++ 访问。

如果必要或方便，可能可以取消 C++ 存储，将类别集和指标 ID 映射移动到 Rust，并根据需要通过 FFI 移动信息。

测试方法从 nsIFOG 运行（以便我们可以在 xpcshell 的 JS 中使用它们）到静态 JOG:: 函数。

构建集成

如果 JOG 检测到我们是工件构建（通过检查 MOZ_ARTIFACT_BUILDS），它会生成 jogfile.json 并确保将其放置在 GreD（在 firefox 二进制文件旁边）。

jogfile.json 仅包含在运行时注册它们所需的指标和 Ping 信息。（它不知道标签或描述，只知道事物的形状和名称）

首次尝试从 Glean 全局变量获取指标类别或从 GleanPings 全局变量获取 Ping 时，会读取此文件。

是的，这是在主线程上。是的，这是同步的。是的，这是文件 I/O。

由于这是开发人员构建，我们认为为了支持工件构建，这样做是值得的。

如果我们对此判断错误，并且应该对 JOG 施加其他条件，请 联系我们。

如果出现奇怪的情况，请删除 objdir/dist/bin/jogfile.json

有时，您添加的指标或 Ping 在运行 Firefox 时可能不会出现。对于这些和其他奇怪的情况，解决方案是相同的：从 objdir 的 dist/bin 目录中删除 jogfile.json，然后重试。

如果您将工件和非工件 objdir 分开（这是良好的实践），则这种情况不应发生。

如果尽管做了正确的事情，您仍然看到这种情况或其他奇怪的事情，那么这是一个错误。请 在 Toolkit :: Telemetry 中提交