• メトリクスの定義と検証
  • メトリクスkey_path
  • メトリックのステータス
  • メトリクスvalue_type
  • メトリクスtime_frame
  • データカテゴリー
  • YAML メトリック定義の例
  • 新しいメトリクス定義の作成
  • Service Pingペイロードにダイナミックに追加されたメトリクス
• メトリクス辞書
  • クエリをクリップボードにコピー

メトリクス辞書ガイド

サービス Pingメトリクスは、個々の YAML ファイル定義で定義され、そこからメトリクス・ディクショナリが構築されます。現在、メトリクス・ディクショナリは 1 日に 1 回自動的に構築されます。YAML ファイルでメトリクスに変更が加えられると、24 時間以内にディクショナリでその変更を確認できます。このガイドでは、ディクショナリとその実装方法について説明します。

メトリクスの定義と検証

メトリクス定義の検証にはJSONスキーマを使用しています。

このプロセスは、Service Ping に定義された一貫性のある有効なメトリクスを保証するためのものです。すべてのメトリクスには、以下の条件があります：

• 定義されたJSONスキーマに準拠していること。
• 一意のkey_path を持つこと。
• オーナーを持つこと。

メトリクスはすべて YAML ファイルに格納されます：

• config/metrics

各メトリクスは、いくつかのフィールドで構成される個別の YAML ファイルで定義されます：

メトリクスkey_path

メトリックのkey_path は、JSON Service Ping ペイロード内の位置です。

key_path は、. で区切られた複数の部分から Composer することができ、一意でなければなりません。

トップレベルのキーの1つにメトリクスを追加することをお勧めします：

• settings設定に関連するメトリクスについては、次のように最上位キーの1つに追加することをお勧めします。
• counts_weekly: 直近7日間のデータを持つカウンター用。
• counts_monthly: 直近28日間のデータを持つカウンターの場合。
• counts: すべての期間のデータを持つカウンターの場合。

メトリックのステータス

メトリクス定義は、以下のステータスのいずれかを持つことができます：

• active:メトリクスは使用され、データをレポーターします。
• broken:メトリックは壊れたデータを報告するか（例えば、-1フォールバック）、データを全く報告しません。としてマークされたメトリクスは broken、repair_issue_url 属性も持っている必要があります。
• removed:メトリクスは削除されましたが、古いバージョンのGitLabで動作するインスタンスから送信されるService Pingペイロードに表示されることがあります。

メトリクスvalue_type

メトリック定義は、value_type に以下の値のいずれかを指定できます：

• boolean
• number
• string
• object:value_type: object を持つメトリクスは、オブジェクトのJSONスキーマへのリンクを持つvalue_json_schema を持たなければなりません。一般的に、私たちは複雑なオブジェクトを避け、boolean、number、string のいずれかの値型を好みます。value_type: object を使用するメトリクスの例として、topology (/config/metrics/settings/20210323120839_topology.yml) があり、/config/metrics/objects_schemas/topology_schema.jsonに関連するスキーマがあります。

メトリクスtime_frame

メトリックの時間枠は、time_frame フィールドとメトリックのdata_source に基づいて計算されます。

データカテゴリー

メトリクスを分類するために以下のカテゴリを使用します：

• operational:オペレーションに必要なデータ。
• optional:メトリクスのデフォルト値。収集が任意であるデータ。管理エリアで有効または無効にできます。
• subscription:ライセンスに関するデータ。
• standard:データを収集する際に含まれる識別子の標準セット。

集約メトリクスは、2 つ以上の子メトリクスの合計であるメトリクスです。Service Ping は、報告される Service Ping ペイロードにデータが含まれるかどうかを判断するために、集約メトリクスのデータ・カテゴリを使用します。

YAML メトリック定義の例

リンク先のuuid YAML ファイルには、uuid メトリックが GitLab インスタンス一意識別子であるメトリック定義の例が含まれています。

key_path: uuid
description: GitLab instance unique identifier
product_section: analytics
product_stage: analytics
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
distribution:
- ce
- ee
tier:
- free
- premium
- ultimate

新しいメトリクス定義の作成

GitLabのコードベースには、新しいメトリクス定義を作成するための専用のジェネレーターが用意されています。

一意性を保つために、生成されたファイルにはISO 8601形式のタイムスタンプ接頭辞が含まれます。

ジェネレーターはキーパスのリストと3つのオプションを引数にとります。対応する場所にメトリックYAML定義を作成します：

• --ee --no-ee メトリックがEE用かどうかを示します。
• --dir=DIR メトリックのディレクトリを示します。以下のいずれかである必要があります：counts_7d 7d,counts_28d,28d,counts_all,all,settings,license.
• --class_name=CLASS_NAME 計装クラスを示します。例えば、UsersCreatingIssuesMetric 、UuidMetric

単一メトリクスの例

bundle exec rails generate gitlab:usage_metric_definition counts.issues --dir=7d --class_name=CountIssues
// Creates 1 file
// create  config/metrics/counts_7d/issues.yml

複数のメトリクスの例

bundle exec rails generate gitlab:usage_metric_definition counts.issues counts.users --dir=7d --class_name=CountUsersCreatingIssues
// Creates 2 files
// create  config/metrics/counts_7d/issues.yml
// create  config/metrics/counts_7d/users.yml

bundle exec rails generate gitlab:usage_metric_definition counts.issues --ee --dir=7d --class_name=CountUsersCreatingIssues
// Creates 1 file
// create  ee/config/metrics/counts_7d/issues.yml

Service Pingペイロードにダイナミックに追加されたメトリクス

Redis HLLのメトリクスはService Pingのペイロードに自動的に追加されます。

各メトリックには YAML メトリック定義が必要です。Redis HLL イベント用のメトリクス定義を作成する専用のジェネレーターが用意されています。

ルートキーはredis_hll_counters であるため、ジェネレータはcategory とevents の引数をとり、それぞれのイベントに対して2つのメトリック定義を作成します(週単位と月単位の時間枠に対して)：

単一メトリクスの例

bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues count_users_closing_issues
// Creates 2 files
// create  config/metrics/counts_7d/count_users_closing_issues_weekly.yml
// create  config/metrics/counts_28d/count_users_closing_issues_monthly.yml

複数のメトリクスの例

bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues count_users_closing_issues count_users_reopening_issues
// Creates 4 files
// create  config/metrics/counts_7d/count_users_closing_issues_weekly.yml
// create  config/metrics/counts_28d/count_users_closing_issues_monthly.yml
// create  config/metrics/counts_7d/count_users_reopening_issues_weekly.yml
// create  config/metrics/counts_28d/count_users_reopening_issues_monthly.yml

EEで使用されるメトリクス定義を作成するには、--ee フラグを追加します。

bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues users_closing_issues --ee
// Creates 2 files
// create  config/metrics/counts_7d/i_closed_weekly.yml
// create  config/metrics/counts_28d/i_closed_monthly.yml

メトリクス辞書

メトリクス辞書は別のアプリケーションです。

Service Pingで使用できるメトリクスはすべて、Metrics Dictionaryにあります。

クエリをクリップボードにコピー

メトリクスがSisenseにデータを持っているか確認するには、クエリをクリップボードにコピーする機能を使用します。これにより、Sisense ですぐに使えるクエリがコピーされます。このクエリは、指定したメトリクスに関するGitLab.comの直近5件のサービスpingデータを取得します。Service Ping メトリックのデータが Sisense にあるかどうかを確認する方法については、こちらのデモをご覧ください。