GitLab Duo導入メトリクスと分析

GitLab Duo導入メトリクスと分析

このプロジェクトでは、次のものを組み合わせて、エンドツーエンドのGitLab Duoの使用状況分析を提供します:

• Duo GraphQL Data Collection – GitLab GraphQL APIクライアントによってバックアップされたDuoコレクタースクリプトを呼び出す汎用Pythonオーケストレーター。
• Duo Usage Metrics Pipeline – GitLabグループのDuo使用状況データを定期的に収集および集計するCIジョブ。
• Duo Analytics Dashboard – Duoの導入、使用強度、エンゲージメントの傾向を示すGitLab Pagesでホストされるダッシュボード。

はじめに

これらのProject CI/CD Variablesを設定して、実行する分析パイプラインを制御できます:

Steps for Quick Start

1. このリポジトリをフォークします。
2. Project Settings → CI/CD → Variablesの設定 → CI/CD → 変数に移動します。
3. 上記の変数を、ご使用の環境に適した値で追加します。
4. 任意の間隔でscheduled pipelineを設定します。Duoの使用状況の収集は負荷が高くなる可能性があるため、once per dayの実行をお勧めします。
5. スケジュールされたパイプラインを手動で実行するか、スケジュールを待ちます。
6. パイプラインが完了したら、Deploy → PagesにあるPagesアプリケーションを開き、Duo Analyticsダッシュボードにアクセスします。

GitLab Pagesのデプロイ（Duoメトリクス）

Duoメトリクスが有効になっている場合、Duoパイプラインの完了後にPagesのデプロイが自動的に行われます:

• Duo Metrics Pipeline → https://your-username.gitlab.io/project-name/duo-metrics/のようなURLにデプロイします。
• Main Landing Page → https://your-username.gitlab.io/project-name/で使用可能。利用可能なダッシュボードへのリンクがあります。

ランディングページは、どのダッシュボードが存在するかを自動的に検出し、ENABLE_DUO_METRICS="true"の場合、Duo関連のリンクを表示します。

ローカル開発とテスト

Duo分析のローカルテストの場合（CIなし）:

1. Pythonと依存関係がインストールされていることを確認してください（たとえば、リポジトリルートでpoetry installを使用）。
2. ローカル.envまたはShellセッションで、必要な環境変数を設定します:
   • DUO_TOKEN
   • GROUP_PATH
3. 汎用オーケストレータースクリプトを実行して、raw Duoの使用状況データを収集します:

python ai_raw_data_collection.py

1. ローカルのpublic/またはdocs/フォルダー（設定によって異なります）で生成されたメトリクスを開くか、ソリューションコンポーネントプロジェクトのドキュメントに記載されているように、ローカルでダッシュボードを実行します。

Duoダッシュボードの機能

Duo Analyticsダッシュボードは、GitLab Duoの導入とAIの使用パターンに焦点を当てています。以下を含みます:

• License & Adoption Analytics – Duoアクセスを持つユーザー数と、実際に使用しているユーザー数を追跡します。
• Code Suggestions Analytics – AIアシストコーディングの承諾率、提案のボリューム、言語分布を監視します。
• Duo Chat Analytics – チャットのやり取り、ユーザーコホート、会話ボリュームを表示します。
• User Engagement Analytics – 使用レベル（非アクティブ、実験、通常、ヘビー）でユーザーをセグメント化します。
• Language & Workflow Performance – プログラミング言語またはワークフロー別に、Duoの有効性（承諾率、提案の使用状況など）を分析します。

これらのメトリクスは、Duo関連のシグナルからのみ派生しています。このダッシュボードを使用するために、従来のプロジェクトメトリクスは必要ありません。

Duo使用状況データ収集パイプライン

Duo導入メトリクスは、以下に依存するCI駆動のデータ収集パイプラインによって作成されます:

• generic Python orchestrator：ai_raw_data_collection.py
• 再利用可能なGitLab GraphQL API client：gitlab_graphql_api

オーケストレーター：ai_raw_data_collection.py

スクリプトai_raw_data_collection.pyは、次の役割を担います:

• 環境/CI変数（GROUP_PATH、DUO_TOKEN、パイプライン構成など）の読み取り。
• 具体的なDuo使用状況クエリを実装する1つ以上のcollector scriptsの呼び出し。
• 調整:
  • グループおよびプロジェクト全体のページネーション。
  • Duoの使用状況イベントの日時ウィンドウまたはサンプリング戦略。
  • 一貫性のある分析に適した形式（例：CSV / JSON）への結果の正規化。
• Duoダッシュボードとダウンストリームの集計手順が消費する場所への収集されたデータの書き込み。

これは、raw Duo使用状況データを収集するためのgeneric entry pointとして機能するため、次のことが可能です:

• CI設定を変更せずに、Duo関連の新しいコレクターを追加します。
• 環境変数またはCIジョブを介して、実行するコレクターを制御します。

GitLab GraphQL APIクライアントとコレクション

Duo関連のすべてのGraphQLロジックは、gitlab_graphql_api Pythonパッケージ、特に以下にカプセル化されています:

• gitlab_graphql_api > collections

キーとなるアイデア:

• GraphQL client abstraction – 中央クライアントは、GitLab GraphQLエンドポイントに対する認証、ページネーション、およびエラー処理を処理します。
• コレクションクラス – collectionsモジュールは、構造化されたデータを取得するためのメソッドを公開する、より高レベルの抽象化（「プロジェクトコレクション」や「ユーザーコレクション」など）を提供します。Duoコレクターはこれらを使用して、:
  • 特定のGROUP_PATHのグループとプロジェクトをフェッチします。
  • Duoの使用状況フィールドとAI関連のアクティビティーをクエリします。
• Versioned API usage – オーケストレーターを変更せずに、GitLabがDuo関連のGraphQLフィールドを改善または拡張するにつれて、同じコレクションAPIを拡張できます。

Duoコレクターはこれらのコレクションクラスをインポートし、必要な特定のクエリを定義します（たとえば、AIコードの提案、チャットの使用状況イベント、またはユーザーレベルの導入統計の数をフェッチするなど）。

注: Duoの使用状況に関するGraphQLのスキーマとフィールド名は、gitlab_graphql_api > collectionsのコレクションクラスとともにドキュメント化されています。Duoメトリクスのために収集されたデータを拡張またはカスタマイズするときは、それらのドキュメントを使用してください。

Duoデータ収集の設定

パイプラインはカスタマイズできますが、一般的なDuoのみのセットアップには、次のものが必要です:

• Minimal CI configuration:
  • ENABLE_DUO_METRICS="true"を設定して、Duoパイプラインを有効にします。
  • オプションで、ENABLE_PROJECT_METRICS="false"を設定して、Duo以外のパイプラインを無効にします。
• ai_raw_data_collection.pyで使用されるEnvironment variables:

これらを設定すると、ai_raw_data_collection.pyを実行するCIジョブは次のようになります:

1. gitlab_graphql_apiコレクションを使用して、指定されたグループのDuo使用状況データをクエリします。
2. 書き込むことができるraw Duo使用状況アーティファクト:
   • レポートに集計。
   • Duoダッシュボードによって直接読み込む。

Duoメトリクスの拡張

Duo導入メトリクスを追加または改善するには、:

1. 新しいDuoシグナルに関連するGitLab GraphQLフィールド（たとえば、追加の使用状況カウンターまたは新しいAI機能）をIdentifyします。
2. 次のコレクタースクリプトをUpdate or addします:
   • gitlab_graphql_api > collectionsの抽象化を使用します。
   • 既存のDuoコレクターと一貫性のある形式でデータを書き込みます。
3. Wire the collectorしてai_raw_data_collection.pyに接続します（または、環境変数を介して制御します）。
4. 必要に応じて、新しいフィールドを使用および視覚化するようにUpdate the dashboardします。

GraphQLアクセスとページネーションロジックがgitlab_graphql_api内にカプセル化されているため、Duoメトリクスを拡張するということは、通常、:

• オーケストレーターの変更は最小限です。
• 新しいメトリクスのモデリングとダッシュボードの更新に焦点を当てます。

リソース

• GitLab Duo導入メトリクスソリューションコンポーネントプロジェクト
• gitlab_graphql_apiパッケージとcollectionsモジュール（Duo GraphQLの使用パターン用）