• Usage Pingとは何ですか？
  • なぜUsage Pingを有効にする必要があるのでしょうか？
  • 制限事項
• 使用法 Ping ペイロード
• 使用状況Pingの無効化
• 使用法 Pingリクエストフロー
• 使用状況Pingの仕組み
• 使用状況Pingの実装
  • なぜバッチカウントなのか
  • 通常のバッチカウンター
  • 識別バッチカウンター
  • Redisカウンタ
  • 代替カウンター
  • クエリ
• Usage Pingの開発とテスト
  • 1. Railsコンソールを使って手動でカウンタをテストします。
  • 2. SQLクエリの生成
  • 3. クエリの最適化 #データベースラボ
  • 4. メトリクス定義の追加
  • 5. バージョン・アプリケーションに新しいメトリクスを追加
  • 6. 機能ラベルの追加
  • 7. 変更履歴ファイルの追加
  • 8. テレメトリーレビューの依頼
  • オプション：Prometheusの使用状況Pingのテスト
    • Omnibusコンテナでのテスト
    • GitLab開発ツールキットでのテスト
• 使用統計の定義
• 使用例 Ping ペイロード

使用Pingガイド

• GitLab Enterprise Edition 8.10で導入されました。
• GitLab Enterprise Edition 8.12では、より多くの統計情報が追加されました。
• 9.1でGitLab Coreに移動しました。
• GitLab Ultimate 11.2ではより多くの統計情報が追加されました。

このガイドでは、Usage Pingの目的と実装方法について説明します。

テレメトリーについては、こちらを参照：

• テレメトリーガイド
• Snowplowガイド

その他の便利なリンク

• テレメトリ方向
• データ分析プロセス
• プロダクトマネージャーのためのデータ
• データインフラ

Usage Pingとは何ですか？

• GitLabは毎週、GitLab Inc.に利用状況データを含むペイロードを送信します。 利用状況Pingは、製品、サポート、営業チームに役立つハイレベルなデータを提供します。 プロジェクト名、ユーザー名、その他の特定のデータは送信しません。 利用状況Pingの情報は匿名ではなく、インスタンスのホスト名にリンクされています。 利用状況Pingの送信は任意で、どのインスタンスでもアナリティクスを無効にすることができます。
• 使用状況データは、主にインスタンスのデータベース内のさまざまなテーブルの行数で構成されています。 これらのカウントを月ごと（あるいは週ごと）に比較することで、インスタンスが製品内のさまざまな機能をどのように使用しているかを大まかに把握することができます。 カウントに加えて、GitLab インストールを分類して理解するのに役立つその他の事実も収集されます。
• GitLab にとって利用状況の ping は重要です。この ping を使ってステージ月間アクティブユーザー数(SMAU) を計算し、ステージや機能の成功を測定しています。
• usage pingを有効にすると、GitLabは他のインスタンスからデータを収集し、インスタンスの使用統計をユーザーに表示できるようになります。

なぜUsage Pingを有効にする必要があるのでしょうか？

• Usage Pingの主な目的は、より良いGitLabを構築することです。 GitLabの使われ方に関するデータを収集することで、機能/ステージの採用と利用状況をより良く理解することができます。これにより、GitLabがどのように価値を高めているかを理解し、私たちのチームが人々がGitLabを使う理由をより良く理解することができ、この知識によって私たちはより良い製品決定を行うことができます。
• 使用状況pingをアクティブにする利点として、GitLabではGitLabインストールのユーザーのアクティビティを時系列で分析することができます。
• 使用状況のpingをアクティブにするメリットとして、GitLabはDevOpsスコアを提供し、プランニングからモニタリングまで、インスタンス全体のConcurrent DevOpsの採用状況を概観できます。
• より良い、より積極的なサポートを得ることができます。
• GitLabへの投資から最大限の価値を引き出すためのインサイトとアドバイスを得ることができます。 あなたの組織で多くの機能や価値が採用されていないことを知りたくないですか？
• DevOpsプロセスを改善するための具体的なアドバイスや推奨事項とともに、他の類似組織（匿名化）との比較を示すレポートを入手できます。
• Usage Pingはデフォルトで有効になっています。 無効にするには、Disable Usage Pingを参照してください。

制限事項

• Usage Pingは、ページビュー、リンククリック、ユーザーセッションのようなフロントエンドのイベントを追跡せず、バックエンドの集約されたイベントのみに焦点を当てます。
• このような制限があるため、GitLab.comでより詳細なアナリティクスを行うにはSnowplowでインストゥルメントを作成することをお勧めします。また、セルフマネージドではUsage Pingを使ってバックエンドの集約イベントをトラッキングすることをお勧めします。

使用法 Ping ペイロード

GitLab Inc.に送信された正確なJSONペイロードは、管理パネルで確認できます。 ペイロードを確認するには、以下の手順に従います：

1. 管理エリア > 設定 > メトリクスとプロファイリングに移動します。
2. 使用統計セクションを展開します。
3. ペイロードのプレビューボタンをクリックします。

ペイロードの例については、使用例 Ping ペイロードを参照してください。

使用状況Pingの無効化

GitLab UIでUsage Pingを無効にするには、管理パネルのSettingsページでUsage Pingチェックボックスのチェックを外してください。

Usage Ping を無効にし、今後管理パネルから設定できないようにするには、Omnibus のインストー ルでgitlab.rbを次のように設定します：

gitlab_rails['usage_ping_enabled'] = false

ソース・インストールでは、gitlab.ymlで以下を設定できます：

production: &base
  # ...
  gitlab:
    # ...
    usage_ping_enabled: false

使用法 Pingリクエストフロー

次の例は、GitLabインスタンス、Versionsアプリケーション、ライセンスアプリケーション、Salesforce、GitLabのS3バケット、GitLabのSnowflakeデータウェアハウス、Sisense間の基本的なリクエスト/レスポンスのフローを示しています：

使用状況Pingの仕組み

1. Usage PingcronジョブはSidekiqで毎週実行されるように設定されています。
2. cronジョブが実行されると、GitLab::UsageData.to_json。
3. GitLab::UsageData.to_json は他の400以上のカウンターメソッド呼び出しにカスケードダウンします。
4. すべてのメソッド呼び出しのレスポンスは、GitLab::UsageData.to_jsonの単一のJSONペイロードにマージされます。
5. その後、JSONペイロードがVersionsアプリケーションにポストされます。

使用状況Pingの実装

Usage Pingは、カウンターとオブザベーションの2種類のデータで構成されています。 カウンターは、CIパイプラインが何回実行されたかなど、あるイベントがどれくらいの頻度で発生したかを追跡します。 単調で、常に上昇傾向にあります。 オブザベーションは、1つまたは複数のGitLabインスタンスから収集されたファクトで、任意のデータを持つことができます。 データの個別性のため、収集方法に関する一般的なガイドラインはありません。

usage_data.rb、4種類のカウンターがあります：

• 通常のバッチカウンタ:与えられたActiveRecord_Relationの単純なカウント
• Distinctバッチカウンタ:指定されたカラムの指定されたActiveRecord_RelationのDistinctカウント
• 代替カウンタ：設定や構成に使用します。
• RedisCounters:メモリ内のカウントに使用されます。 このメソッドはデータの不正確さのため非推奨となり、永続的なメソッドに置き換えられる予定です。

なぜバッチカウントなのか

大きなテーブルの場合、PostgreSQLはMVCC（Multi-version Concurrency Control）のために行のカウントに時間がかかることがあります。 バッチカウントは、1つの大きなクエリを複数の小さなクエリに分割してカウントする方法です。 例えば、1つのクエリで1,000,000レコードのクエリを実行する代わりに、バッチカウントを使用すると、10,000レコードずつのクエリを100回実行することができます。 バッチカウントは、1つのバッチクエリが1つの長い実行クエリよりも大幅に短いため、データベースのタイムアウトを回避するのに便利です。

GitLab.comでは、15秒のクエリタイムアウトがある非常に大きなテーブルがあるので、タイムアウトに遭遇しないようにバッチカウントを使っています。 以下はGitLab.comのいくつかのテーブルのサイズです：

バッチカウンティングには、Ordinary Batch Counters とDistinct Batch Countersの2つの方法があります。 バッチカウンティングでは、最大、最小、範囲のクエリを計算するために、カラムにインデックスが必要です。 場合によっては、カウンタに関係するカラムに特殊なインデックスを追加する必要があります。

通常のバッチカウンター

ActiveRecord::StatementInvalid エラーを処理します。

指定された ActiveRecord_Relation の単純なカウント。

方法：count(relation, column = nil, batch: true, start: nil, finish: nil)

議論：

• relation カウントを実行する ActiveRecord_Relation
• column デフォルトはプライマリキーです。
• batch: バッチカウントを使用するためのデフォルトtrue
• start複雑な分単位の計算を避けるために、バッチカウントをカスタムで開始します。
• end複雑な分単位の計算を避けるために、バッチ終了時のカウントをカスタマイズできます。

例：

count(User.active)
count(::Clusters::Cluster.aws_installed.enabled, :cluster_id)
count(::Clusters::Cluster.aws_installed.enabled, :cluster_id, start: ::Clusters::Cluster.minimum(:id), finish: ::Clusters::Cluster.maximum(:id))

識別バッチカウンター

ActiveRecord::StatementInvalid エラーを処理します。

指定されたカラムの、指定された ActiveRecord_Relation の識別カウント。

方法：distinct_count(relation, column = nil, batch: true, start: nil, finish: nil)

議論：

• relation カウントを実行する ActiveRecord_Relation
• column デフォルトはプライマリキーです。
• batch: バッチカウントを使用するためのデフォルトtrue
• start複雑な分単位の計算を避けるために、バッチカウントをカスタムで開始します。
• end複雑な分単位の計算を避けるために、バッチ終了時のカウントをカスタマイズできます。

例：

distinct_count(::Project, :creator_id)
distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id))
distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id')

Redisカウンタ

::Redis::CommandError とGitlab::UsageDataCounters::BaseCounter::UnknownEventを処理 ブロックが送信されたときに -1 を返すか、counter(Gitlab::UsageDataCounters) が送信されたときにすべての値を持つハッシュ -1 を返す Redis カウンタの実装が 2 つ異なるため、動作が異なります。

方法：redis_usage_data(counter, &block)

議論：

• counterfallback_totals メソッドを実装した からのカウンタ。Gitlab::UsageDataCounters
• またはblock: で評価されます。

使用例：

redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter)
redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] }

Redisカウンタは非推奨になりつつあるので、代わりにSnowplowイベントを使うようにしてください。 私たちはセルフマネージドイベントトラッキングを構築中で、これが利用可能になれば、すべてのRedisカウンタをSnowplowイベントに変換します。

代替カウンター

StandardError と -1 へのフォールバックを処理します。これにより、1 つの例外が発生しても、すべてのメジャーが失敗することはありません。 主に設定と構成に使用されます。

方法：alt_usage_data(value = nil, fallback: -1, &block)

議論：

• valueこの場合、値は単に返されます。
• またはblock: で評価されます。
• fallback: -1失敗しているメトリクスに使用される共通値。

使用例：

alt_usage_data { Gitlab::VERSION }
alt_usage_data { Gitlab::CurrentSettings.uuid }
alt_usage_data(999)

クエリ

運用メトリクスを Usage Ping の一部とする場合、データベースや Redis を使ったクエリでは有用なデータは得られないでしょう。 その代わりに、Prometheus を使うのが適切かもしれません。GitLab のアーキテクチャコンポーネントのほとんどが Prometheus にメトリクスを公開しており、それをクエリバックして集計し、使用状況データとして含めることができるからです。

yield Prometheus にメトリクスをクエリするために、ヘルパー・メソッドが用意されています。このメソッドは、PrometheusClientが完全に設定されていることを前提としています：

with_prometheus_client do |client|
  response = client.query('<your query>')
  ...
end

APIを使用してデータをクエリする方法については、PrometheusClient 定義を参照してください。

Usage Pingの開発とテスト

1. Railsコンソールを使って手動でカウンタをテストします。

# count
Gitlab::UsageData.count(User.active)
Gitlab::UsageData.count(::Clusters::Cluster.aws_installed.enabled, :cluster_id)

# count distinct
Gitlab::UsageData.distinct_count(::Project, :creator_id)
Gitlab::UsageData.distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id))

2. SQLクエリの生成

Railsコンソールが生成されたSQLクエリを返します。

使用例：

pry(main)> Gitlab::UsageData.count(User.active)
   (2.6ms)  SELECT "features"."key" FROM "features"
   (15.3ms)  SELECT MIN("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4))
   (2.4ms)  SELECT MAX("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4))
   (1.9ms)  SELECT COUNT("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4)) AND "users"."id" BETWEEN 1 AND 100000

3. クエリの最適化 #データベースラボ

SQLクエリを#database-lab に貼り付けて、クエリがスケール時にどのように実行されるかを確認します。

• #database-lab はSlackのチャンネルで、本番サイズの環境を使ってクエリをテストします。
• GitLab.comの本番データベースには15秒のタイムアウトがあります。
• コールドキャッシュを使用する場合、単一のクエリの実行時間は1秒以下でなければなりません。
• 実行時間を短縮するために、関係するカラムに特化したインデックスを追加します。

クエリの実行を理解するために、MRの説明に以下の情報を追加します：

• time_period テストがあるカウンターについては、両方のケースの情報を追加します：
  • time_period = {} 全期間
  • time_period = { created_at: 28.days.ago..Time.current } 直近28日間
• 最適化前後の実行プランとクエリ時間
• インデックスと時刻に対して生成されたクエリ
• 上下実行のマイグレーション出力

また、#database-lab 、explain.depesz.comも使用しています。詳しくはデータベースレビューガイドをご覧ください。

クエリ最適化作業の例：

• 例1
• 例2

4. メトリクス定義の追加

メトリクスを追加、変更、更新する場合は、使用統計定義テーブルを更新してください。

5. バージョン・アプリケーションに新しいメトリクスを追加

新しいメトリクスを Versions Application に追加する必要があるかどうかを確認します。usage_data スキーマと使用データ・パラメータの受け入れを参照してください。counts キーの counts下に追加されたメトリクスは、すべて列にcounts 保存 countsされます。

詳細については、Usage Pingにインスツルメンテーションを追加するプロセスを参照してください。

6. 機能ラベルの追加

新しい Usage Ping メトリクスのマージ・リクエストにfeature ラベルを追加します。 これらはユーザー向けの変更で、Usage Ping 機能の拡張の一部です。

7. 変更履歴ファイルの追加

変更履歴の入力ガイドに従ってください。

8. テレメトリーレビューの依頼

GitLab.com では、Telemetry 関連のファイルを監視するために DangerBot をセットアップしており、DangerBot が Telemetry のレビューを推奨します。 レビューを希望する場合は、MR に@gitlab-org/growth/telemetry/engineers と明記してください。

オプション：Prometheusの使用状況Pingのテスト

提出されたデータにPrometheusからクエリされたメトリクスが含まれており、それを検査・検証したい場合は、Prometheusサーバーがローカルで稼働していること、さらにそれぞれのGitLabコンポーネントがそのサーバーにメトリクスをエクスポートしていることを確認する必要があります。 Prometheusから送られてくるデータをテストする必要がない場合は、Prometheusサーバーが稼働していなくてもUsage Pingは優雅に低下するはずなので、それ以上のアクションは必要ありません。

現在、Prometheusにデータをエクスポートできるコンポーネントは3種類あり、Usage Pingに含まれています：

• node_exporter - ホスト・マシンからのノード・メトリクスのエクスポート
• gitlab-exporter - 様々なGitLabコンポーネントからプロセスメトリクスをエクスポート
• SidekiqやRailsサーバーなど、独自のメトリクスをエクスポートする様々なGitLabサービス

Omnibusコンテナでのテスト

これはPrometheusベースのUsage Pingをテストするために推奨される方法です。

変更を確認する最も簡単な方法は、CI経由でコードブランチから新しいOmnibusイメージをビルドし、イメージをダウンロードしてローカルのコンテナインスタンスを実行することです：

1. マージリクエストから、qa ステージをクリックし、package-and-qa ジョブをトリガーします。 このジョブは、omnibus-gitlab-mirror プロジェクト](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/-/pipelines)の[下流パイプラインで Omnibus ビルドをトリガーします。
2. 下流のパイプラインでは、gitlab-docker のジョブが終了するまで待ちます。
3. ジョブ・ログを開き、バージョンを含む完全なコンテナ名を検索します。 これは、次のような形式になります：registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>.
4. ローカルマシンで、GitLab Dockerレジストリにログインしていることを確認します。 この手順は、Authenticating to the GitLab Container Registryにあります。
5. ログインしたら、次の方法で新しい画像をダウンロードします。docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>
6. OmnibusのGitLabコンテナをDockerで操作して実行する方法については、OmnibusドキュメントのGitLab Dockerイメージを参照してください。

GitLab開発ツールキットでのテスト

実際のGitLabのデプロイをエミュレートするときに多くの困難が伴うので、これはあまり推奨されないアプローチです。

GDKは現在、Prometheusサーバーやnode_exporter 、他のGitLabコンポーネントと一緒に実行するように設定されていません。もしそうしたいのであれば、PrometheusでGDKをモニタリングするのが良いスタートです。

GCKには、Prometheus ベースの Usage Ping をテストするための限定的なサポートがあります。 デフォルトでは、多くのコンポーネントをスクレイピングするように設定された Prometheus サービスが既に付属していますが、以下の制限があります：

• 現在、gitlab-exporter インスタンスを実行していないため、Gitaly などのサービスからのいくつかのprocess_* メトリクスが欠落している可能性があります。
• node_exporterを実行していますが、docker-compose サービスはホストをエミュレートしています。つまり、通常であれば、実行中の他のどのサービスとも関連付けられないように自分自身を報告します。本番環境では、ノード・メトリクスがどのように報告されるかは異なります。ノード・メトリクスは、node_exporter常に任意のノード上で他の GitLab コンポーネントと一緒にプロセスとして実行されます。Usage Ping の観点からは、どのノード・データも、実行中のどのサービスとも関連付けられないように見えます。この問題を軽減するために、 node_exporter web サービスに GCK を任意に「割り当て」ました。つまり、Usage Ping では、このサービスnode_* のメトリクスのみが表示されます。

使用統計の定義

使用例 Ping ペイロード

以下は、Usage Pingペイロードの内容例です。

{
  "uuid": "0000000-0000-0000-0000-000000000000",
  "hostname": "example.com",
  "version": "12.10.0-pre",
  "installation_type": "omnibus-gitlab",
  "active_user_count": 999,
  "recorded_at": "2020-04-17T07:43:54.162+00:00",
  "edition": "EEU",
  "license_md5": "00000000000000000000000000000000",
  "license_id": null,
  "historical_max_users": 999,
  "licensee": {
    "Name": "ABC, Inc.",
    "Email": "email@example.com",
    "Company": "ABC, Inc."
  },
  "license_user_count": 999,
  "license_starts_at": "2020-01-01",
  "license_expires_at": "2021-01-01",
  "license_plan": "ultimate",
  "license_add_ons": {
  },
  "license_trial": false,
  "counts": {
    "assignee_lists": 999,
    "boards": 999,
    "ci_builds": 999,
    ...
  },
  "container_registry_enabled": true,
  "dependency_proxy_enabled": false,
  "gitlab_shared_runners_enabled": true,
  "gravatar_enabled": true,
  "influxdb_metrics_enabled": true,
  "ldap_enabled": false,
  "mattermost_enabled": false,
  "omniauth_enabled": true,
  "prometheus_enabled": false,
  "prometheus_metrics_enabled": false,
  "reply_by_email_enabled": "incoming+%{key}@incoming.gitlab.com",
  "signup_enabled": true,
  "web_ide_clientside_preview_enabled": true,
  "ingress_modsecurity_enabled": true,
  "projects_with_expiration_policy_disabled": 999,
  "projects_with_expiration_policy_enabled": 999,
  ...
  "elasticsearch_enabled": true,
  "license_trial_ends_on": null,
  "geo_enabled": false,
  "git": {
    "version": {
      "major": 2,
      "minor": 26,
      "patch": 1
    }
  },
  "gitaly": {
    "version": "12.10.0-rc1-93-g40980d40",
    "servers": 56,
    "clusters": 14,
    "filesystems": [
      "EXT_2_3_4"
    ]
  },
  "gitlab_pages": {
    "enabled": true,
    "version": "1.17.0"
  },
  "database": {
    "adapter": "postgresql",
    "version": "9.6.15"
  },
  "app_server": {
    "type": "console"
  },
  "avg_cycle_analytics": {
    "issue": {
      "average": 999,
      "sd": 999,
      "missing": 999
    },
    "plan": {
      "average": null,
      "sd": 999,
      "missing": 999
    },
    "code": {
      "average": null,
      "sd": 999,
      "missing": 999
    },
    "test": {
      "average": null,
      "sd": 999,
      "missing": 999
    },
    "review": {
      "average": null,
      "sd": 999,
      "missing": 999
    },
    "staging": {
      "average": null,
      "sd": 999,
      "missing": 999
    },
    "production": {
      "average": null,
      "sd": 999,
      "missing": 999
    },
    "total": 999
  },
  "analytics_unique_visits": {
    "g_analytics_contribution": 999,
    ...
  },
  "usage_activity_by_stage": {
    "configure": {
      "project_clusters_enabled": 999,
      ...
    },
    "create": {
      "merge_requests": 999,
      ...
    },
    "manage": {
      "events": 999,
      ...
    },
    "monitor": {
      "clusters": 999,
      ...
    },
    "package": {
      "projects_with_packages": 999
    },
    "plan": {
      "issues": 999,
      ...
    },
    "release": {
      "deployments": 999,
      ...
    },
    "secure": {
      "user_container_scanning_jobs": 999,
      ...
    },
    "verify": {
      "ci_builds": 999,
      ...
    }
  },
  "usage_activity_by_stage_monthly": {
    "configure": {
      "project_clusters_enabled": 999,
      ...
    },
    "create": {
      "merge_requests": 999,
      ...
    },
    "manage": {
      "events": 999,
      ...
    },
    "monitor": {
      "clusters": 999,
      ...
    },
    "package": {
      "projects_with_packages": 999
    },
    "plan": {
      "issues": 999,
      ...
    },
    "release": {
      "deployments": 999,
      ...
    },
    "secure": {
      "user_container_scanning_jobs": 999,
      ...
    },
    "verify": {
      "ci_builds": 999,
      ...
    }
  },
  "topology": {
    "duration_s": 0.013836685999194742,
    "application_requests_per_hour": 4224,
    "failures": [],
    "nodes": [
      {
        "node_memory_total_bytes": 33269903360,
        "node_cpus": 16,
        "node_uname_info": {
          "machine": "x86_64",
          "sysname": "Linux",
          "release": "4.19.76-linuxkit"
        },
        "node_services": [
          {
            "name": "web",
            "process_count": 16,
            "process_memory_pss": 233349888,
            "process_memory_rss": 788220927,
            "process_memory_uss": 195295487,
            "server": "puma"
          },
          {
            "name": "sidekiq",
            "process_count": 1,
            "process_memory_pss": 734080000,
            "process_memory_rss": 750051328,
            "process_memory_uss": 731533312
          },
          ...
        ],
        ...
      },
      ...
    ]
  }
}