Help us learn about your current experience with the documentation. Take the survey.

指标字典指南

Service Ping 的指标定义在各个 YAML 文件中，这些文件用于构建 Metrics Dictionary。目前，指标字典每小时自动构建一次。

  • 当 YAML 文件中的指标发生更改时，您可以在更改部署到生产环境后的 1 小时内看到字典中的更改。
  • 当 YAML 文件中的事件发生更改时，您可以在更改合并到 master 分支后的 1 小时内看到字典中的更改。

本指南描述了字典及其实现方式。

指标定义和验证

我们使用 JSON Schema 来验证指标定义。

此过程旨在确保为 Service Ping 定义的一致且有效的指标。所有指标必须：

  • 符合定义的 JSON schema。
  • 拥有唯一的 key_path。
  • 拥有所有者。

目前，tier 是指标定义文件的必填字段之一，但我们现在正逐步用 tiers 替换 tier。因此，在指标定义文件中添加 tiers 字段是有效的。在替换过程完成之前，tier 和 tiers 都是可以添加到指标定义文件中的有效字段。

所有指标都存储在 YAML 文件中：

只有具有指标定义 YAML 且状态不为 removed 的指标才会被添加到 Service Ping JSON 载荷中。

每个指标都在一个 YAML 文件中定义，该文件包含多个字段：

字段名 必填 附加信息
key_path 是 指标的 JSON 键路径，Service Ping 载荷中的位置。
description 是
product_group 是 拥有该指标的 group。
product_categories 否 array；指标所代表的使用情况的 功能类别。某些指标可能对应多个类别或没有类别。
value_type 是 string；string, number, boolean, object 之一。
status 是 string；指标的 状态，可设置为 active、removed、broken。
time_frame 是 string 或 array；可设置为 7d、28d、all、none 或包含除 none 外任意这些值的数组。
data_source 是 string；可设置为 database、redis、redis_hll、prometheus、system、license、internal_events 等值。
data_category 是 string；指标的 类别，可设置为 operational、optional、subscription、standard。默认值为 optional。
instrumentation_class 否 string；用于 data_source 不是 internal_events 的指标。请参阅 实现该指标的类。
performance_indicator_type 否 array；可设置为 gmau, smau, paid_gmau, umau, customer_health_score, devops_report, lighthouse, or leading_indicator 之一。
tiers 是 array；可包含 free、premium 或 ultimate 中的一个或组合。跟踪功能可用的 版本层级。这应该是详细的，并包含指标可用的所有版本层级。
milestone 是 指标引入的里程碑，以及指标在官方 GitLab 发布后可用于 GitLab 自托管实例的时间。
milestone_removed 否 指标被移除的里程碑。已移除指标必需。
introduced_by_url 是 引入指标使其可用于 GitLab 自托管实例的合并请求的 URL。
removed_by_url 否 移除指标的合并请求的 URL。已移除指标必需。
repair_issue_url 否 为状态为 broken 的指标创建的问题的 URL。
options 否 object：计算指标值所需的选项信息。

指标 key_path

指标的 key_path 是 JSON Service Ping 载荷中的位置。

key_path 可以由多个用 . 分隔的部分组成，并且必须是唯一的。

如果指标定义具有数组 time_frame，YAML 文件中定义的 key_path 将为每个包含的时间帧自动添加后缀：

时间帧 key_path 后缀
all 无后缀
7d _weekly
28d _monthly

Metrics Dictionary 中显示的 key_path 包含这些后缀。

指标状态

指标定义可以具有以下状态之一：

  • active：指标被使用并报告数据。
  • broken：指标报告错误数据（例如，-1 回退），或者完全不报告数据。标记为 broken 的指标还必须具有 repair_issue_url 属性。
  • removed：指标已被移除，但它可能出现在从运行旧版本 GitLab 的实例发送的 Service Ping 载荷中。

指标 value_type

指标定义的 value_type 可以具有以下值之一：

  • boolean
  • number
  • string
  • object：具有 value_type: object 的指标必须具有 value_json_schema，其中包含指向该对象的 JSON schema 的链接。 通常，我们避免使用复杂对象，而是倾向于使用 boolean、number 或 string 值类型之一。 使用 value_type: object 的指标示例是 topology（/config/metrics/settings/20210323120839_topology.yml）， 它在 /config/metrics/objects_schemas/topology_schema.json 中有相关的 schema。

指标 time_frame

指标的时间帧基于指标的 time_frame 字段和 data_source 计算。当 time_frame 是数组时，将为每个包含的时间帧计算指标的值。

数据源 时间帧 描述
any none 一种不随时间跟踪的数据类型，如设置和配置信息
database all 指标活动的整个时间（全时间段）
database 7d 9天前到2天前
database 28d 30天前到2天前
internal_events all 指标活动的整个时间（全时间段）
internal_events 7d 最近一个完整的周
internal_events 28d 最近4个完整的周

数据类别

我们使用以下类别对指标进行分类：

  • operational：运营目的所需的数据。
  • optional：指标的默认值。可选择收集的数据。这可以在 Admin 区域中启用或禁用。
  • subscription：与许可相关的数据。
  • standard：收集数据时包含的标准标识符集合。

示例 YAML 指标定义

链接的 uuid YAML 文件包含一个示例指标定义，其中 uuid 指标是 GitLab 实例的唯一标识符。

key_path: uuid
description: GitLab instance unique identifier
product_group: analytics_instrumentation
value_type: string
status: active
milestone: 9.1
instrumentation_class: UuidMetric
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521
time_frame: none
data_source: database
tier:
- free
- premium
- ultimate
tiers:
- free
- premium
- ultimate

创建新的指标定义

GitLab 代码库提供了专用的生成器来创建新指标，这些生成器也会创建有效的指标定义文件：

为了确保唯一性，生成的文件包含 ISO 8601 格式的时间戳前缀。

性能指标

要使用指标定义来管理 性能指标：

  1. 创建包含相关更改的合并请求。
  2. 使用标签 ~"analytics instrumentation"、"~Data Warehouse::Impact Check"。
  3. 更新指标定义的 performance_indicator_type 字段。
  4. 在 GitLab Product Data Insights 项目中使用 PI 图表帮助模板 创建一个问题，以可视化新指标。

指标字典

Metrics Dictionary 是一个独立的应用程序。

Service Ping 中所有可用的指标都在 Metrics Dictionary 中。