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

GitLab 应用服务级别指标 (SLIs)

可以直接在 Ruby 代码库中定义 Service Level Indicators(SLIs)。这样做可以将操作及其成功标准的定义与代码实现保持紧密关联，并让构建功能的人员能够轻松定义这些功能的监控方式。

现有的 SLI

rails_request
global_search_apdex
global_search_error_rate
global_search_indexing_apdex
sidekiq_execution

定义新的 SLI

可以使用 Gitlab::Metrics::Sli::Apdex 或 Gitlab::Metrics::Sli::ErrorRate 类来定义一个 SLI。当你定义一个 SLI 时，Rails 应用会发出两个 Prometheus counters。这两个计数器的工作方式基本相同，都包含一个总操作次数。Apdex 使用成功率来计算成功比例，而 ErrorRate 使用错误率来计算错误比例。

定义了以下指标：

Gitlab::Metrics::Sli::Apdex.new('foo') 定义：
- gitlab_sli_foo_apdex_total 用于测量总数。
- gitlab_sli_foo_apdex_success_total 用于成功测量的数量。
Gitlab::Metrics::Sli::ErrorRate.new('foo') 定义：
- gitlab_sli_foo_total 用于测量总数。
- gitlab_sli_foo_error_total 用于错误测量的数量。因为此指标是错误率，所以错误数会被总数除。

如本例所示，它们可以共享一个基础名称（本例中为 foo）。当它们指代同一操作时，我们推荐这样做。

你应该使用 Apdex 来衡量成功操作的性能。你无需衡量失败请求的性能，因为该性能应由 ErrorRate 来跟踪。例如，你可以衡量请求是否在指定的延迟阈值内完成。

你应该使用 ErrorRate 来衡量不成功操作的比例。例如，你可以衡量失败的请求是否返回了大于或等于 500 的 HTTP 状态码。

在第一次抓取之前，使用所有可能的标签组合初始化 SLI 至关重要。这样可以避免在计算中使用这些计数器时产生令人困惑的结果。

要初始化一个 SLI，请使用 .initialize_sli 类方法，例如：

Gitlab::Metrics::Sli::Apdex.initialize_sli(:received_email, [
  {
    feature_category: :team_planning,
    email_type: :create_issue
  },
  {
    feature_category: :service_desk,
    email_type: :service_desk
  },
  {
    feature_category: :code_review_workflow,
    email_type: :create_merge_request
  }
])

指标必须在第一次被抓取前完成初始化。这目前发生在 on_master_start lifecycle event 期间。由于这会延迟应用的就绪状态，直到指标初始化返回，请确保理解并接受由此带来的额外开销。

跟踪 SLI 的操作

在新定义的 SLI 中跟踪操作可以这样做：

Gitlab::Metrics::Sli::Apdex[:received_email].increment(
  labels: {
    feature_category: :service_desk,
    email_type: :service_desk
  },
  success: issue_created?
)

在此 SLI 上调用 #increment 将增加总的 Prometheus 计数器

gitlab_sli:received_email_apdex:total{ feature_category='service_desk', email_type='service_desk' }

如果传递的 success: 参数为真，则成功计数器也会增加：

gitlab_sli:received_email_apdex:success_total{ feature_category='service_desk', email_type='service_desk' }

对于错误率 SLI，等效的参数名为 error:：

Gitlab::Metrics::Sli::ErrorRate[:merge].increment(
  labels: {
    merge_type: :fast_forward
  },
  error: !merge_success?
)

在服务监控和告警中使用 SLI

当应用为新 SLI 发出指标时，需要从 metrics catalog 中消费这些指标以生成告警，并将其纳入阶段组和 GitLab.com 整体可用性的错误预算中。

首先，将新的 SLI 添加到 Application-SLI library。之后，添加以下信息：

name: 代码中定义的 SLI 名称。例如 received_email。
significantLabels: 属于这些指标的 Prometheus 标签数组。例如：["email_type"]。如果 SLI 的显著标签包含 feature_category，这些指标也将被纳入阶段组的错误预算。
featureCategory: 如果 SLI 适用于单个功能类别，你可以通过此字段静态指定它，以将 SLI 纳入阶段组的错误预算。
description: 解释 SLI 的 Markdown 字符串。它将显示在仪表盘和告警中。
kind: 指标的类型。例如 sliDefinition.apdexKind。

完成后，运行 make generate 为新的 SLI 生成记录规则。此命令会为所有发出这些指标的服务创建记录，这些指标按 significantLabels 进行聚合。

创建一个包含这些更改的合并请求，并请求可扩展性（Scalability）团队成员进行审查。

当这些更改被合并，并且 Mimir 中的聚合记录完成后，查询 Mimir 以查看新聚合指标的成功比例。例如：

sum by (environment, stage, type)(application_sli_aggregation:rails_request:apdex:success:rate_1h)
/
sum by (environment, stage, type)(application_sli_aggregation:rails_request:apdex:weight:score_1h)

这显示了成功比例，可以指导你在将此 SLI 添加到服务时设定一个合适的 SLO（服务级别目标）。

然后，将 SLI 添加到相应的服务目录文件中。例如，web 服务：

rails_requests:
  sliLibrary.get('rails_request_apdex')
    .generateServiceLevelIndicator({ job: 'gitlab-rails' })

要传递额外的选择器并覆盖 SLI 的属性，请参阅 service monitoring documentation。

具有静态定义功能类别的 SLI 已经可以在指定的 Slack 频道中接收关于该 SLI 的告警。有关更多信息，请阅读 alert routing documentation。在 this project 中，我们正在扩展此功能，以便源指标中带有 feature_category 标签的 SLI 的告警也可以被路由。

如有任何问题，请随时在 the Scalability issue tracker 中创建 issue，或在 Slack 的 #g_scalability 频道中找到我们。