• 命名法
• どのように動作するか
• データベース・メトリクス
  • 通常のバッチカウンターの例
  • 識別バッチカウンタの例
  • 合計の例
  • 平均の例
• Redisのメトリクス
  • 可用性に制約のあるRedisのメトリクス
• Redis HyperLogLogメトリクス
  • 可用性に制約のあるRedis HyperLogLogメトリクス
• 集約されたメトリクス
  • 利用可能性に制約のある集約メトリクス
• 数値メトリクス
• 一般的なメトリクス
• Prometheusメトリクス
• インスツルメンテーションクラスのサポート
• 新しいメトリクス・インストルメンテーション・クラスの作成
• Service Pingメトリクスをインスツルメンテーション・クラスにマイグレーション
• メトリクスのトラブルシューティング

メトリクス計測ガイド

このガイドでは、メトリクス・インスツルメンテーションを使用して Service Ping メトリクスを開発する方法について説明します。

ビデオ・チュートリアルについては、「Adding Service Ping metric via instrumentation class」を参照してください。

命名法

• 計装クラス：
  • メトリクスクラスのいずれかを継承します：DatabaseMetric RedisMetric,RedisHLLMetric,NumbersMetric またはGenericMetric 。
  • Service Ping メトリックの値を計算するロジックを実装します。

• メトリック定義Service Data メトリック YAML 定義。

• ハードニングメソッドのハードニングはメソッドが安全に失敗し、-1 のようなフォールバック値を返すことを保証するプロセスです。

どのように動作するか

メトリクス定義にはinstrumentation_class フィールドがあり、クラスを設定することができます。

定義されたインスツルメンテーション・クラスは、既存のメトリクス・クラスのいずれかを継承する必要があります：DatabaseMetric RedisMetric,RedisHLLMetric,NumbersMetric またはGenericMetric 。

現在の慣例では、1つのインストルメンテーション・クラスが1つのメトリクスに対応します。まれに、Redisメトリクスのような例外もあります。単一のインストルメンテーションクラスを複数のメトリクスに使用する場合は、@gitlab-org/analytics-section/analytics-instrumentation/engineers のメンバーにご相談ください。

インスツルメンテーション・クラスを使用することで、サービス Ping 生成のプロセス全体を壊すことなく、メトリクスが個別にフェールセーフできるようになります。

メトリクスのインスツルメンテーションを定義するために、ドメイン固有の言語(DSL) を構築しました。

データベース・メトリクス

データベース・メトリクスを使用すると、特定のインスタンスに存在するイシューのカウントなど、データベースに保存されているデータを追跡できます。

• operation:指定されたrelation 、count 、distinct_count 、sum 、averageのいずれかに対するオペレーション。
• relation:operation を実行したいオブジェクトのActiveRecord::Relation を返すラムダを割り当てます。割り当てられたラムダは、最大1つのパラメータを受け取ることができます。パラメータはハッシュ化され、メトリクス定義のoptions キーの下に格納されます。
• start:バッチカウントの開始値を指定します。デフォルトはrelation.minimum(:id) です。
• finish:バッチカウントの終了値を指定します。デフォルトはrelation.maximum(:id) です。
• cache_start_and_finish_as:start とfinish の値のキャッシュ・キーを指定し、キャッシュを設定します。start およびfinish が異なるメトリクス計算間で再利用されるべき高価なクエリである場合に、この呼び出しを使用します。
• available?:メトリックをレポーターするかどうかを指定します。デフォルトはtrue です。
• timestamp_column:オプションで、時間制約付きメトリクスのレコードのフィルタリングに使用するメトリックのタイムスタンプ列を指定し ます。既定値はcreated_at です。

データベース・メトリクスを追加するマージ・リクエストの例。

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class CountIssuesMetric < DatabaseMetric
          operation :count

          relation ->(options) { Issue.where(confidential: options[:confidential]) }
        end
      end
    end
  end
end

通常のバッチカウンターの例

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class CountIssuesMetric < DatabaseMetric
          operation :count

          start { Issue.minimum(:id) }
          finish { Issue.maximum(:id) }

          relation { Issue }
        end
      end
    end
  end
end

識別バッチカウンタの例

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class CountUsersAssociatingMilestonesToReleasesMetric < DatabaseMetric
          operation :distinct_count, column: :author_id

          relation { Release.with_milestones }

          start { Release.minimum(:author_id) }
          finish { Release.maximum(:author_id) }
        end
      end
    end
  end
end

合計の例

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class JiraImportsTotalImportedIssuesCountMetric < DatabaseMetric
          operation :sum, column: :imported_issues_count

          relation { JiraImportState.finished }
        end
      end
    end
  end
end

平均の例

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class CountIssuesWeightAverageMetric < DatabaseMetric
          operation :average, column: :weight

          relation { Issue }
        end
      end
    end
  end
end

Redisのメトリクス

Redisメトリクスを使用すると、データベースに保存されないイベント、たとえば検索バーが何回使用されたかのカウントを追跡できます。

Redis メトリクスを追加するマージ・リクエストの例.

RedisMetric クラスは、単純なカウンタ・クラス（BaseCounter を継承し、PREFIX およびKNOWN_EVENTS 定数を設定するだけのクラス）を持つ Redis メトリクスのinstrumentation_class としてのみ使用できます。カウンタ・クラスに追加のロジックが含まれている場合は、RedisMetricを継承した新しいinstrumentation_classを作成する必要があります。この新しいクラスには、カウンタ・クラスの追加ロジックを含める必要があります。

必須オプション

• eventイベント名。
• prefix Gitlab::UsageDataCounters 名前空間のカウンタ・クラスで使用されるPREFIX 定数の値。

source_code_pushes イベントの一意な値を数えます。

time_frame: all
data_source: redis
instrumentation_class: RedisMetric
options:
  event: pushes
  prefix: source_code

可用性に制約のあるRedisのメトリクス

Redis メトリクスをいくつかの条件下でのみレポートで使用できるようにする場合は、RedisMetric クラスの子クラスである新しいクラスでこれらの条件を指定する必要があります。

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class MergeUsageCountRedisMetric < RedisMetric
          available? { Feature.enabled?(:merge_usage_data_missing_key_paths) }
        end
      end
    end
  end
end

YAMLセットアップでクラスの名前も使わなければなりません。

time_frame: all
data_source: redis
instrumentation_class: MergeUsageCountRedisMetric
options:
  event: pushes
  prefix: source_code

Redis HyperLogLogメトリクス

Redis HyperLogLogメトリクスを使用すると、データベースに保持されないイベントを追跡し、ユニーク・ユーザーなどの一意の値に対してインクリメントすることができます。

RedisHLL メトリクスを追加するマージリクエストの例.

i_quickactions_approve イベントの一意な値を数えます。

time_frame: 28d
data_source: redis_hll
instrumentation_class: RedisHLLMetric
options:
  events:
    - i_quickactions_approve

可用性に制約のあるRedis HyperLogLogメトリクス

Redis HyperLogLogメトリクスをいくつかの条件下でのみレポートで利用できるようにする場合は、RedisHLLMetric クラスの子クラスである新しいクラスでこれらの条件を指定する必要があります。

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class MergeUsageCountRedisHLLMetric < RedisHLLMetric
          available? { Feature.enabled?(:merge_usage_data_missing_key_paths) }
        end
      end
    end
  end
end

YAMLセットアップでクラスの名前も使わなければなりません。

time_frame: 28d
data_source: redis_hll
instrumentation_class: MergeUsageCountRedisHLLMetric
options:
  events:
    - i_quickactions_approve

集約されたメトリクス

集約メトリクス機能では、イベントの集合で発生したデータ属性の数（pseudonymized_user_ids など）をインサイトできます。たとえば、新規イシューの作成や新規マージリクエストのオープンなど、複数のアクションを実行したユーザー数を集計できます。

YAML ファイルを使用して、集約するメトリクスを定義できます。以下の引数が必要です：

• options.events:メトリクス・データに集約するイベント名のリスト。このリスト内のすべてのイベントは、同じデータ・ソースを使用する必要があります。その他のデータ・ソース要件については、「Database sourced aggregated metrics」および「Redis sourced aggregated metrics」を参照してください。
• options.aggregate.operator:集約されたメトリクス・データのカウント方法を定義するオペレーション。使用可能なオペレーションは以下のとおりです：
  • OR:重複を削除し、リストされたイベントのいずれかをトリガしたすべてのエントリをカウントします。
  • AND:重複を削除し、以下のすべてのイベントをトリガーして観測されたすべての要素を数えます。
• options.aggregate.attribute:イベント間で集約される属性を指す情報。
• time_frame:1 つ以上の有効な時間枠。これらを使用して、集約されたメトリクスに含まれるデータを、特定の日付範囲内のイベントに制限します。有効な時間枠は以下のとおりです：
  • 7d:過去 7 日間のデータ。
  • 28d:過去28日間のデータ。
  • all:database 、集計されたメトリクスでのみ利用可能です。
• data_source:集約メトリクスに含まれるすべてのイベント・データを収集するために使用されるデータ・ソース。有効なデータ・ソースは以下のとおりです：
  • database
  • redis_hll

AggregatedMetric メトリクスを追加するマージ・リクエストの例については、マージ・リクエスト98206を参照してください。

少なくとも1つのイベントで発生した一意のuser_ids を数えます：incident_management_alert_status_changed incident_management_alert_assigned,incident_management_alert_todo,incident_management_alert_create_incident.

time_frame: 28d
instrumentation_class: AggregatedMetric
data_source: redis_hll
options:
    aggregate:
        operator: OR
        attribute: user_id
    events:
        - `incident_management_alert_status_changed`
        - `incident_management_alert_assigned`
        - `incident_management_alert_todo`
        - `incident_management_alert_create_incident`

利用可能性に制約のある集約メトリクス

Aggregated メトリクスを特定の条件下でのみレポートで使用できるようにする場合は、AggregatedMetric クラスの子クラスである新しいクラスでこれらの条件を指定する必要があります。

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class MergeUsageCountAggregatedMetric < AggregatedMetric
          available? { Feature.enabled?(:merge_usage_data_missing_key_paths) }
        end
      end
    end
  end
end

YAMLセットアップでクラスの名前も使わなければなりません。

time_frame: 28d
instrumentation_class: MergeUsageCountAggregatedMetric
data_source: redis_hll
options:
    aggregate:
        operator: OR
        attribute: user_id
    events:
        - `incident_management_alert_status_changed`
        - `incident_management_alert_assigned`
        - `incident_management_alert_todo`
        - `incident_management_alert_create_incident`

数値メトリクス

• operation:与えられたdata ブロックに対するオペレーション。現在のところ、add のオペレーションのみをサポートしています。
• data: 数値の配列を含むblock を指定します。
• available?:メトリックをレポーターするかどうかを指定します。デフォルトはtrue です。

# frozen_string_literal: true

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
          class IssuesBoardsCountMetric < NumbersMetric
            operation :add

            data do |time_frame|
              [
                 CountIssuesMetric.new(time_frame: time_frame).value,
                 CountBoardsMetric.new(time_frame: time_frame).value
              ]
            end
          end
        end
      end
    end
  end
end

YAML セットアップに計測クラス名も含める必要があります。

time_frame: 28d
instrumentation_class: IssuesBoardsCountMetric

一般的なメトリクス

ジェネリック・メトリクスは、インスタンスのデータベース・バージョンなど、他のメトリクスに使用できます。Observationsタイプのデータは、常にGenericメトリック・カウンタ・タイプを持ちます。

• value:メトリクスの値を指定します。
• available?:メトリックをレポーターするかどうかを指定します。デフォルトはtrue です。

汎用メトリクスを追加するマージリクエストの例。

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class UuidMetric < GenericMetric
          value do
            Gitlab::CurrentSettings.uuid
          end
        end
      end
    end
  end
end

Prometheusメトリクス

このインスツルメンテーション・クラスでは、Prometheus クライアント・オブジェクトをvalue ブロックの引数として渡すことで、Prometheus クエリを処理できます。Prometheusのエラー処理はブロックの中で行ってください。

• value:メトリクスの値を指定します。第1引数にPrometheusクライアントオブジェクトを渡します。
• available?:メトリックをレポーターするかどうかを指定します。デフォルトはtrue です。

Prometheus メトリクスを追加するマージリクエストの例。

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class GitalyApdexMetric < PrometheusMetric
          value do |client|
            result = client.query('avg_over_time(gitlab_usage_ping:gitaly_apdex:ratio_avg_over_time_5m[1w])').first

            break FALLBACK unless result

            result['value'].last.to_f
          end
        end
      end
    end
  end
end

インスツルメンテーションクラスのサポート

以下のサポートがあります：

• count distinct_count,estimate_batch_distinct_count,sum,average のデータベース・メトリクスがサポートされています。
• Redisのメトリクス。
• Redis HLLのメトリクス。
• add メトリクスを使用します。
• 設定や構成に基づくメトリクス。

のサポートはありません：

• addhistogram データベース・メトリクス。

これらをサポートするための進捗を追跡することができます。

新しいメトリクス・インストルメンテーション・クラスの作成

Service Ping メトリクスのスタブ・インスツルメンテーションを作成するには、専用のジェネレーターを使用します：

ジェネレーターは、引数としてクラス名を取り、以下のオプションを指定します：

• --type=TYPE 必須。メトリクス・タイプを示します。のいずれかでなければなりません：database generic,redis,numbers.
• --operation database &numbers タイプの場合は必須。
  • database の場合は、以下のいずれかでなければなりません：count distinct_count,estimate_batch_distinct_count,sum,average.
  • numbers の場合は、add のいずれかでなければなりません。
• --ee メトリクスがEE用かどうかを示します。

rails generate gitlab:usage_metric CountIssues --type database --operation distinct_count
        create lib/gitlab/usage/metrics/instrumentations/count_issues_metric.rb
        create spec/lib/gitlab/usage/metrics/instrumentations/count_issues_metric_spec.rb

Service Pingメトリクスをインスツルメンテーション・クラスにマイグレーション

このガイドでは、Service Ping メトリクスをlib/gitlab/usage_data.rb またはee/lib/ee/gitlab/usage_data.rb からインスツルメンテーション・クラスにマイグレーションする方法について説明します。

1. メトリックのタイプを選択します：

• データベース・メトリクス
• Redis HyperLogLogメトリクス
• Redisメトリクス
• メトリクス
• 汎用メトリクス

1. インスツルメンテーション・クラスの場所を決定：ee.NET Frameworkの下か外か ee

2. インストルメンテーション・クラス・ファイルを生成します。

3. インストルメンテーション・クラスの本体を作成します：

   • メトリクス用のコードロジックを追加します。これはusage_data.rb のメトリクス実装に似ているかもしれません。
   • 個々のメトリクスにテストを追加するspec/lib/gitlab/usage/metrics/instrumentations/。
   • Service Pingのテストを追加します。

4. メトリクス定義ファイルを生成します。

5. lib/gitlab/usage_data.rb またはee/lib/ee/gitlab/usage_data.rb からコードを削除します。

6. spec/lib/gitlab/usage_data.rb またはee/spec/lib/ee/gitlab/usage_data.rb からテストを削除してください。

メトリクスのトラブルシューティング

メトリクスは、すぐに明確にはならない理由で失敗することがあります。その失敗は、パフォーマンスのイシューやその他の問題に関連していることがあります。次のペア・セッションのビデオでは、実際に失敗したメトリクスを調査する例を示します。