가치 스트림 분석 개발 지침

가치 스트림 분석 (VSA)을 GitLab에서 구성하는 방법에 대한 정보는 분석 문서를 참조하세요.

가치 스트림 분석이 작동하는 방식은?

가치 스트림 분석은 두 개의 타임스탬프 열 또는 타임스탬프 표현 사이의 기간을 계산하고 데이터에 대해 다양한 집계를 실행합니다.

예시:

  • 병합 요청 생성 시간과 병합 요청 병합 시간 사이의 기간.
  • 이슈 생성 시간과 이슈 종료 시간 사이의 기간.

이 기간은 다양한 방법으로 노출됩니다:

  • 집계: 중간값, 평균
  • 나열: 개별 병합 요청 및 이슈 레코드의 기간 나열

기간 외에, 우리는 단계 내에서 레코드 수를 노출합니다.

기능 가용성

  • 그룹 레벨 (라이선스 있음): Ultimate 또는 Premium 구독이 필요합니다. 이 버전이 가장 많은 기능을 포함하고 있습니다.
  • 프로젝트 레벨 (라이선스 있음): 프로젝트 레벨 VSA에 기능을 지속적으로 추가하여 그룹 레벨 VSA에 맞추고 있습니다.
  • 프로젝트 레벨 (FOSS): 그대로 유지합니다.
기능 그룹 레벨 (라이선스 있음) 프로젝트 레벨 (라이선스 있음) 프로젝트 레벨 (FOSS)
사용자 정의 가치 스트림 생성 예 기본 단계로만 하나의 가치 스트림이 있음 기본 단계로만 하나의 가치 스트림이 있음
사용자 정의 단계 생성 예 아니요 아니요
필터링 (작성자, 레이블, 마일스톤 등) 예 예 예
단계 시간 차트 예 아니요 아니요
총 시간 차트 예 아니요 아니요
유형별 작업 차트 예 아니요 아니요
DORA 메트릭 예 예 아니요
주기 시간 및 선도 시간 요약 (생명주기 메트릭) 예 예 아니요
새로운 이슈, 커밋 및 배포 (생명주기 메트릭) 커밋 제외 예 예
집계 백엔드 사용 예 아니요 아니요
날짜 필터 동작 항목을 날짜 범위 내에서 완료된로 필터링 작성 날짜별로 항목을 필터링합니다. 작성 날짜별로 항목을 필터링합니다.
인가 적어도 기자 적어도 기자 공개될 수 있음.

VSA 코어 도메인 오브젝트

단계

단계는 시작 및 종료 이벤트의 이벤트 쌍을 나타내며, 추가 메타데이터(단계의 이름 등)를 가지고 있습니다. 단계는 백엔드에서 정의된 매칭 규칙 내에서 사용자에 의해 구성 가능합니다.

예시 단계: 코드 리뷰

  • 시작 이벤트 식별자: 병합 요청 생성 시간.
  • 시작 이벤트 열: merge_requests.created_at 타임스탬프 열을 사용합니다.
  • 종료 이벤트 식별자: 병합 요청 병합 시간.
  • 종료 이벤트 열: merge_request_metrics.merged_at 타임스탬프 열을 사용합니다.
  • 단계 이벤트 해시 ID: 시작 및 종료 이벤트 식별자 쌍에 대한 계산된 해시입니다.
    • 두 단계가 시작 및 종료 이벤트의 동일한 구성을 가지고 있다면, 그들의 단계 이벤트 해시 IDs는 동일합니다.
    • 단계 이벤트 해시 ID는 나중에 분할된 데이터베이스 테이블에 집계된 데이터를 저장하는 데 사용됩니다.

역사적으로, 가치 스트림 분석은 여섯 단계를 정의했으며, 이는 구독 내용에 관계없이 항상 끝 사용자에게 제공됩니다.

가치 스트림

가치 스트림은 이벤트들의 컨테이너 개체입니다. DevOps 라이프사이클의 다양한 측면에 중점을 두는 여러 개의 가치 스트림이 그룹당 있을 수 있습니다.

이벤트

이벤트는 가치 스트림 분석 기능의 가장 작은 구성 요소입니다. 단계는 두 개의 이벤트로 구성됩니다:

  • 시작 이벤트
  • 종료 이벤트

이러한 이벤트들은 기간 계산에 중요한 역할을 합니다.

공식: 기간 = 종료 이벤트 시간 - 시작 이벤트 시간

기간 계산을 유연하게 만들기 위해 각 Event는 별도의 클래스로 구현됩니다. 이들은 계산 쿼리에서 사용되는 타임스탬프 표현을 정의하는 데 책임이 있습니다.

Event 클래스 구현

object_type와 timestamp_projection과 같은 몇 가지 메서드를 구현해야 합니다. 가장 중요한 메서드는 다음과 같습니다:

  • object_type
  • timestamp_projection

object_type 메서드는 계산을 위해 어떤 도메인 객체를 쿼리할 지를 정의합니다. 현재 두 모델이 허용됩니다:

  • Issue
  • MergeRequest

기간 계산을 위해 timestamp_projection 메서드가 사용됩니다. 

def timestamp_projection
  # 여기에 타임스탬프 표현을 입력하세요
end

# 이벤트는 계산 시 이슈 생성 시간을 사용합니다
def timestamp_projection
  Issue.arel_table[:created_at]
end

더 복잡한 표현도 가능합니다 (예: COALESCE 사용). 예제를 보려면 기존 이벤트 클래스를 검토하세요.

일부 경우에는 timestamp_projection 메서드를 정의하는 것만으로 충분하지 않을 수 있습니다. 계산 쿼리가 타임스탬프 표현을 포함하는 테이블을 알아야 할 수 있습니다. 각 Event 클래스는 timestamp_projection이 작동하도록 계산 쿼리에 수정을 가하는 것에 책임이 있습니다. 이는 일반적으로 추가 테이블을 조인하는 것을 의미합니다.

예시: issue_metrics 테이블을 조인하고 first_mentioned_in_commit_at 열을 타임스탬프 표현으로 사용하는 경우: 

def object_type
  Issue
end

def timestamp_projection
  IssueMetrics.arel_table[:first_mentioned_in_commit_at]
end

def apply_query_customization(query)
  # 이 경우 쿼리 속성은 Issue 모델을 기준으로 합니다: `Issue.where(...)`
  query.joins(:metrics)
end

시작 및 종료 이벤트 유효성 검사

일부 시작/종료 이벤트 쌍은 서로 “호환되지” 않을 수 있습니다. 예를 들어:

  • “이슈 생성”에서 “병합 요청 생성”으로: 이벤트 클래스는 서로 다른 도메인 모델에서 정의되며, object_type 메서드가 다릅니다.
  • “이슈 종료”에서 “이슈 생성”으로: 이슈는 종료되기 전에 생성되어야 합니다.
  • “이슈 종료”에서 “이슈 종료”로: 기간은 항상 0입니다.

StageEvents 모듈은 허용된 start_event 및 end_event 쌍 (PAIRING_RULES 상수)을 설명합니다. 새로운 이벤트를 추가하려면:

  1. Stage 모델에서 enum으로 사용되는 고유한 번호로 ENUM_MAPPING에 항목을 추가하세요.
  2. PAIRING_RULES 해시에서 해당 이벤트와 호환되는 이벤트를 정의하세요.

지원되는 시작/종료 이벤트 쌍:

graph LR; IssueCreated --> IssueClosed; IssueCreated --> IssueFirstAddedToBoard; (이하 생략)

기본 단계

원본 구현에서의 가치 스트림 분석은 7개의 단계를 정의했습니다. 이러한 단계는 항상 각 상위 항목에 대해 사용 가능하지만, 이러한 단계를 변경하는 것은 불가능합니다.

작업을 효율적으로 하고 생성된 레코드 수를 줄이기 위해 기본 단계는 인메모리 객체(지속되지 않음)로 표현됩니다. 사용자가 처음으로 사용자 정의 단계를 만드는 경우, 모든 단계가 지속됩니다. 이 동작은 가치 스트림 분석 서비스 객체에 구현되어 있습니다.

이것은 나중에 단계를 숨기고 정렬할 수 있는 기능을 추가하고 싶어서입니다.

데이터 수집기

DataCollector는 데이터가 데이터베이스에서 쿼리되는 중심지입니다. 이 클래스는 항상 단일 단계에서 작동하며 다음 구성요소로 구성됩니다:

  • BaseQueryBuilder:
    • 초기 쿼리 작성 담당.
    • Stage별 구성 설정 처리: 이벤트 및 이들의 쿼리 사용자 정의.
    • UI에서 오는 매개변수: 날짜 범위.
  • Median: BaseQueryBuilder에서의 쿼리를 사용하여 단계의 중앙값 지속시간 계산.
  • RecordsFetcher: BaseQueryBuilder에서의 쿼리와 가시성 규칙을 적용하기 위한 특정 Finder 클래스를 사용하여 단계의 관련 레코드 로딩.
  • DataForDurationChart: 산포도 차트를 위한 완료 시간(종료 이벤트 타임스탬프)으로 계산된 지속 시간 로딩.

새로운 계산 또는 쿼리를 지원하기 위해서는 DataCollector 클래스에 새로운 메서드 호출로 구현하세요.

통합된 가치 스트림 분석 백엔드를 지원하기 위해 이러한 클래스들은 Aggregated 네임스페이스 내에서 다시 구현되었습니다.

데이터베이스 쿼리 백엔드

VSA는 두 가지 백엔드를 지원합니다: aggregated 및 “live”. “live” 쿼리 백엔드는 언젠가 단계적으로 단계를 줄일 예정인 레거시로 간주될 수 있습니다.

  • “live”: 표준 IssuableFinders를 사용합니다.
  • aggregated: 사전 집계된 데이터베이스 테이블에서 데이터를 쿼리합니다.

고수준 개요

  • Rails Controller(Analytics::CycleAnalytics 모듈): 가치 스트림 분석은 analytics 워크스페이스 내에서 구현된 JSON 엔드포인트를 통해 데이터를 노출합니다. 단계를 구성하는 것도 JSON 엔드포인트(CRUD)로 구현됩니다.
  • 서비스(Analytics::CycleAnalytics 모듈): 모든 Stage 관련 작업은 해당 서비스 객체로 위임됩니다.
  • 모델(Analytics::CycleAnalytics 모듈): 모델은 Stage 객체를 지속하는 데 사용됩니다.
  • 피처 클래스(Gitlab::Analytics::CycleAnalytics 모듈):
    • 쿼리 작성 및 기능별 비즈니스 로직 정의를 담당합니다.
    • DataCollector, Event, StageEvents 등.

프론트엔드

Project VSA는 모든 사용자를 대상으로 사용 가능하며:

  • 티어에 기반한 핵심 및 DORA 메트릭의 혼합물을 포함합니다.
  • 기본 단계의 세트를 사용합니다.

Group VSA는 라이선스 사용자만 사용할 수 있으며 프로젝트 VSA를 확장하여 다음을 포함합니다:

  • 개요 단계.
  • 사용자 정의 가치 스트림 생성 기능.

그룹 및 프로젝트 수준 VSA 프론트엔드는 뷰 및 Vuex로 개발되었으며 비슷한 패턴을 따릅니다:

  • index.js 파일은 URL 쿼리 매개변수를 추출하고 Vue 앱 및 Vuex 스토어를 생성하며 initialize Vuex 작업을 전송합니다.
  • base.vue 파일은 각 페이지, 메트릭, 필터, 차트, 단계 테이블을 렌더링하는 데 사용됩니다.

그룹 VSA Vuex 스토어는 일부 상태 및 로직을 분리하기 위해 Vuex 모듈을 사용합니다.

공통 구성요소

프로젝트 VSA 및 그룹 VSA 간에 공유되는 UI 구성요소는 단계 테이블 및 경로와 같습니다. 이러한 공유 구성요소는 프로젝트 VSA 디렉토리 내의 app/assets/javascripts/cycle_analytics/components에 있으며 필요한 경우 그룹 수준 VSA에 포함됩니다.

그룹 수준 기능에 대한 모든 프론트엔드 코드는 ee/app/assets/javascripts/analytics/cycle_analytics/components에 위치합니다.

테스트

많은 이벤트와 가능한 페어링이 있기 때문에 모든 페어링에 대한 테스트는 불가능합니다. 각 페어링에 대해 최소한 하나의 Event 클래스를 사용하는 테스트 케이스를 갖는 것이 규칙입니다.

새로운 Event를 사용하여 단계에 대한 테스트 케이스를 작성하는 것은 데이터가 두 가지 이벤트에 대해 작성되어야 하기 때문에 어려울 수 있습니다. 이를 조금 더 간단하게 만들기 위해 각 테스트 케이스는 단계가 DataCollector를 통해 테스트되는 data_collector_spec.rb에 구현되어야 합니다. 각 테스트 케이스는 다음과 같은 경우를 포함하는 여러 테스트로 변환됩니다:

  • 다른 상위 항목: Group 또는 Project
  • 다른 계산: Median, RecordsFetcher 또는 DataForDurationChart

VSA 프론트엔드는 두 가지 다른 수준(통합, 단위)에서 철저히 테스트됩니다:

  • Capybara와 RSpec을 통해 실제 백엔드를 사용한 크로스 브라우저 통합 테스트.
  • 사전 생성된 데이터 픽스처를 사용하는 Jest 프론트엔드 테스트.

개발 설정 및 테스트

가치 스트림 분석 실행은 GDK를 통해 수행할 수 있습니다. 기본적으로 프로젝트 수준(FOSS) 버전의 기능을 볼 수 있습니다.

GDK가 작동 중이면 시드 스크립트를 실행하여 일부 데이터를 생성할 수 있습니다: 

SEED_CYCLE_ANALYTICS=true SEED_VSA=true FILTER=cycle_analytics rake db:seed_fu

데이터 생성기 스크립트는 이슈 및 병합 요청 데이터를 생성하는 새 그룹과 새 프로젝트를 만듭니다(스크립트 출력 참조). 기능의 그룹 수준 버전을 볼려면 GDK 인스턴스에 라이선스를 요청해야 합니다.

이 단계 이후에는 그룹 수준 가치 스트림 분석 페이지에 액세스하여 가치 스트림 및 단계를 만들 수 있습니다. 데이터 집계는 지연될 수 있으므로 단계 생성 후에 데이터가 표시되지 않을 수 있습니다. 이 프로세스를 가속화하기 위해 다음 명령을 레일즈 콘솔(rails c)에서 실행할 수 있습니다: 

Analytics::CycleAnalytics::ReaggregationWorker.new.perform

시드 데이터

가치 스트림 분석

가치 스트림 분석을 위한 데이터 시드를 생성하는 방법에 대한 지침은 개발 시드 파일을 참조하세요.