Mozilla Schema Generator

一个用于生成Mozilla遥测ping的完整表示的库。

有关ping的更通用结构，请参阅 Mozilla Pipeline Schemas。此库将那些通用结构填充到我们预期看到的所有探针的适当位置。

遥测集成

我们针对此库的目标有两个通用ping类型

1. 通用ping格式 适用于许多来自Firefox桌面ping的遗留ping，包括“主要”ping
2. Glean ping格式 是Mozilla所有新安装的产品（包括移动浏览器）使用的通用结构。

此库从 探针信息服务 获取那些ping应包含的信息。

数据存储集成

架构的主要用途是与 Schema Transpiler 集成。此存储库生成的架构可以转换为Avro和Bigquery。它们定义了BQ Sink写入的Avro和BigQuery表的架构。

BigQuery限制和拆分

BigQuery对任何单个表有十个列的硬限制。此库可以通过将架构拆分为多个表来考虑这个限制，尽管到目前为止我们已经能够避免这种复杂性。我们保留了架构拆分支持作为未来使用的选项。该选项目前被禁用。

当一个模式被分割时，每个表都有一些在每张表中重复的共同信息，然后是一组仅属于该表的字段。这些表的连接给出了从ping中可用的所有字段的完整集合。

为了决定表分割，我们在配置文件中包含了table_group配置。例如，payload/histograms有table_group: histograms；这表示将输出仅包含直方图的表。

如果一个单独的表超出了配置的列限制，我们将新字段移动到下一个表。例如，我们可以有main_histograms_1和main_histograms_2。

注意：只有当提供--split参数时，才会分割表，目前这个选项在我们的生产配置中未使用。

验证

当我们对数据管道中的模式进行ping验证时，我们使用通用版本而不是由本存储库的机器生成的版本。虽然这里生成的模式由于包括每个指标的显式定义而保证了更正确的性，但在实践中，我们发现有很多边缘情况，其中探针发送了错误的类型，我们需要在加载到BigQuery时将其强制转换为正确的类型。我们还故意将某些复杂类型表示为JSON字符串，并在模式中使用，依赖于BQ加载器将对象转换为字符串。我们仍然可以考虑将来使用生成的模式进行验证，但需要额外的工作来确保不会导致ping的大规模拒绝。

使用

主Ping

生成完整的主Ping模式

mozilla-schema-generator generate-main-ping

生成分表的主Ping模式（用于BigQuery）

mozilla-schema-generator generate-main-ping --split --out-dir main-ping

out-dir参数将是ping的命名空间。

要查看完整的选项列表，请运行mozilla-schema-generator generate-main-ping --help。

Glean

生成所有Glean ping模式 - 每个应用一个，每个ping都发送一个

mozilla-schema-generator generate-glean-pings

将模式写入目录

mozilla-schema-generator generate-glean-pings --out-dir glean-ping

要查看完整的选项列表，请运行mozilla-schema-generator generate-glean-pings --help。

配置文件

配置文件默认位于/config。您也可以在运行生成器时指定自己的配置文件。

配置文件将ping的某些部分与某些类型的探针或指标匹配。配置文件的嵌套与填充的ping相对应。例如，Glean在metrics键下存储探针类型，所以嵌套看起来像这样

{
    "metrics": {
        "string": {
            <METRIC_ID>: {...}
        }
    }
}

虽然通用模式不包括关于特定<METRIC_ID>的信息，但模式生成器确实包括。为了包括在ping的该部分中可以找到的正确指标，我们应将config.yaml文件组织如下

metrics:
    string:
        match:
            type: string

match键表示我们应该用指标填充ping模式中的这部分，而type: string确保我们只在此处放置字符串指标。您可以对来自探针信息服务的ping信息中的任何字段进行精确匹配，该服务还包含桌面探针。

任何字段下都允许几个附加关键字

• contains - 例如process: contains: main，表示process字段是一个数组，并且它应该只匹配包含条目main的项。
• not - 例如send_in_pings: not: glean_ping_info，表示我们应该为send_in_pings匹配任何字段除了glean_ping_info。

table_group键

这个特定字段用于指示在分割模式时，ping的这部分应该包含在哪个表组中。目前我们没有分割任何ping。有关更多信息，请参阅BigQuery限制和分割部分。

允许模式不兼容的更改

在每次运行模式生成器时，都会检查前一个修订版和当前生成修订版之间的不兼容更改。模式不兼容更改包括删除模式或列，或更改列的类型定义。

有两种方法可以绕过这些限制。如果您正在积极开发模式生成器并需要引入模式不兼容更改，请设置 MPS_VALIDATE_BQ=false。

如果需要在生产中引入模式不兼容更改（即 generated-schemas），则修改仓库根目录下的 incompatibility-allowlist。以 {namespace}.{doctype}.{docversion} 的形式添加文档。允许使用通配符。例如，添加以下行以允许删除 my_glean_app 命名空间下的模式

my_glean_app.*

一旦提交成功，应从文档中删除此行。

开发和测试

安装需求

make install-requirements

确保已检出 mozilla-pipeline-schemas 子模块

git submodule init
git submodule update --remote

运行测试

make test

将生成的模式发布到 mozilla-generated-schemas/test-generated-schemas 运行

git fetch origin

git checkout <branch-to-test>

export MPS_SSH_KEY_BASE64=$(cat ~/.ssh/id_rsa | base64)

# generate all schemas for current main
git checkout main && git pull make build && make run

# generate all schemas with changes and compare with main
git checkout <branch-to-test> make build && make run