GitLab Duo 도입 지표 및 분석#

이 프로젝트는 다음을 결합하여 GitLab Duo 사용량에 대한 엔드투엔드 분석을 제공합니다:

• Duo GraphQL 데이터 수집 - GitLab GraphQL API 클라이언트를 기반으로 Duo 수집기 스크립트를 호출하는 범용 Python 오케스트레이터입니다.
• Duo 사용량 지표 파이프라인 - GitLab 그룹의 Duo 사용량 데이터를 주기적으로 수집하고 집계하는 CI job 입니다.
• Duo Analytics 대시보드 - Duo 도입 현황, 사용 강도, 참여 추세를 보여주는 GitLab Pages 기반 대시보드입니다.

시작하기#

다음 프로젝트 CI/CD 변수를 설정하여 실행할 분석 파이프라인을 제어할 수 있습니다:

빠른 시작 단계

1. 이 리포지터리를 포크합니다.
2. Project Settings → CI/CD → Variables로 이동합니다.
3. 환경에 맞는 값으로 위 변수를 추가합니다.
4. 원하는 주기로 예약된 파이프라인을 구성합니다. Duo 사용량 수집은 부하가 클 수 있으므로 하루에 한 번 실행하는 것을 권장합니다.
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 관련 링크를 표시합니다.

로컬 개발 및 테스트#

CI 없이 Duo 분석을 로컬에서 테스트하려면 다음을 수행합니다:

1. Python과 의존성이 설치되어 있는지 확인합니다(예: 리포지터리 루트에서 poetry install 실행).
2. 로컬 .env 또는 셸 세션에서 필요한 환경 변수를 설정합니다:
   • DUO_TOKEN
   • GROUP_PATH
3. 원시 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 기반 데이터 수집 파이프라인으로 생성됩니다:

• 범용 Python 오케스트레이터: ai_raw_data_collection.py
• 재사용 가능한 GitLab GraphQL API 클라이언트: gitlab_graphql_api

오케스트레이터: ai_raw_data_collection.py#

ai_raw_data_collection.py 스크립트는 다음을 담당합니다:

• 환경/CI 변수 읽기(GROUP_PATH, DUO_TOKEN, 파이프라인 구성 등).
• 구체적인 Duo 사용량 쿼리를 구현하는 하나 이상의 수집기 스크립트 호출.
• 다음 조율:
  • 그룹과 프로젝트 전반의 페이지네이션.
  • Duo 사용 이벤트에 대한 날짜/시간 범위 또는 샘플링 전략.
  • 결과를 일관되고 분석하기 쉬운 형식(예: CSV/JSON)으로 정규화.
• 수집된 데이터를 Duo 대시보드와 후속 집계 단계에서 사용하는 위치에 기록.

원시 Duo 사용량 데이터를 수집하기 위한 범용 진입점 역할을 하므로 다음을 수행할 수 있습니다:

• CI 구성을 변경하지 않고 새로운 Duo 관련 수집기 추가.
• 환경 변수 또는 CI job을 통해 실행할 수집기 제어.

GitLab GraphQL API 클라이언트 및 컬렉션#

모든 Duo 관련 GraphQL 로직은 gitlab_graphql_api Python 패키지, 특히 다음 아래에 캡슐화되어 있습니다:

• gitlab_graphql_api > collections

핵심 개념:

• GraphQL client abstraction - 중앙 클라이언트가 GitLab GraphQL 엔드포인트에 대한 인증, 페이지네이션, 오류 처리를 담당합니다.
• Collection classes - collections 모듈은 구조화된 데이터를 가져오는 메서드를 제공하는 상위 수준 추상화("프로젝트 컬렉션"이나 "사용자 컬렉션" 등)를 제공합니다. Duo 수집기는 이를 사용하여 다음을 수행합니다:
  • 주어진 GROUP_PATH에 대한 그룹과 프로젝트 가져오기.
  • Duo 사용량 필드와 AI 관련 활동 쿼리.
• Versioned API usage - GitLab 이 Duo 관련 GraphQL 필드를 개선하거나 확장하더라도 오케스트레이터를 변경하지 않고 동일한 컬렉션 API를 확장할 수 있습니다.

Duo 수집기는 이러한 컬렉션 클래스를 가져와 필요한 특정 쿼리(예: AI 코드 제안 건수, 채팅 사용 이벤트, 사용자 수준 도입 통계 가져오기)를 정의합니다.

Note: Duo 사용량에 대한 GraphQL 스키마와 필드 이름은 gitlab_graphql_api > collections의 컬렉션 클래스와 함께 문서화되어 있습니다. Duo 지표를 위해 수집되는 데이터를 확장하거나 커스터마이징할 때는 해당 문서를 참고합니다.

Duo 데이터 수집 구성#

파이프라인은 커스터마이징할 수 있지만, 일반적인 Duo 전용 설정에는 다음이 필요합니다:

• 최소 CI 구성:
  • ENABLE_DUO_METRICS="true"로 설정하여 Duo 파이프라인을 활성화합니다.
  • 선택적으로 ENABLE_PROJECT_METRICS="false"로 설정하여 Duo가 아닌 파이프라인을 비활성화합니다.
• ai_raw_data_collection.py에서 사용하는 환경 변수:

이 값들을 설정하면 ai_raw_data_collection.py를 실행하는 CI job은 다음을 수행합니다:

1. gitlab_graphql_api 컬렉션을 사용하여 지정된 그룹의 Duo 사용량 데이터를 쿼리합니다.
2. 다음과 같이 활용할 수 있는 원시 Duo 사용량 아티팩트를 기록합니다:
   • 보고서로 집계.
   • Duo 대시보드에서 직접 로드.

Duo 지표 확장#

Duo 도입 지표를 추가하거나 개선하려면 다음을 수행합니다:

1. 새로운 Duo 신호와 관련된 GitLab GraphQL 필드를 식별합니다(예: 추가 사용량 카운터 또는 새로운 AI 기능).
2. 다음을 수행하는 수집기 스크립트를 업데이트하거나 추가합니다:
   • gitlab_graphql_api > collections 추상화를 사용합니다.
   • 기존 Duo 수집기와 일관된 형식으로 데이터를 기록합니다.
3. 수집기를 ai_raw_data_collection.py에 연결합니다(또는 환경 변수로 제어합니다).
4. 필요한 경우 새 필드를 사용하고 시각화하도록 대시보드를 업데이트합니다.

GraphQL 접근과 페이지네이션 로직이 gitlab_graphql_api 내부에 캡슐화되어 있으므로, Duo 지표를 확장하는 작업은 일반적으로 다음을 의미합니다:

• 오케스트레이터의 최소한의 변경.
• 새 지표를 모델링하고 대시보드를 업데이트하는 데 집중.

참고 자료#

• GitLab Duo 도입 지표 솔루션 구성요소 프로젝트
• gitlab_graphql_api 패키지와 collections 모듈(Duo GraphQL 사용 패턴용)