Value stream analytics 개발 가이드라인

Value Stream Analytics(VSA)를 구성하는 방법에 대한 정보는 분석 문서를 참조하세요.

Value Stream Analytics가 작동하는 방식은?

Value Stream Analytics는 두 개의 타임스탬프 열 또는 타임스탬프 표현 사이의 기간을 계산하고 데이터에 대해 다양한 집계를 실행합니다.

예를 들어:

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

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

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

기간 외에도 각 단계 내에서 레코드 수가 노출됩니다.

기능 가용성

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

VSA 핵심 도메인 개체

단계

단계는 추가 메타데이터와 함께 이벤트 쌍(시작 및 종료 이벤트)를 나타냅니다. 단계는 백엔드에서 정의된 페어링 규칙 내에서 사용자에 의해 구성 가능합니다.

예시 단계: 코드 리뷰

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

역사적으로, 가입 여부에 관계없이 사용자에게 항상 사용 가능한 여섯 단계가 Value Stream Analytics에서 정의됩니다.

가치 스트림

가치 스트림은 단계에 대한 컨테이너 개체입니다. DevOps 수명주기의 다양한 측면에 중점을 둔 그룹당 여러 가치 스트림이 있을 수 있습니다.

이벤트

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

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

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

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

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

이벤트 클래스 구현하기

StageEvent 베이스 클래스에서 설명된 여러 메서드를 구현해야 합니다. 가장 중요한 메서드는 다음과 같습니다:

  • 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 메서드를 정의하는 것만으로 충분하지 않습니다. 계산 쿼리는 타임스탬프 표현을 포함하는 테이블이 어디에 있는지 알아야 합니다. 각 이벤트 클래스는 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. ENUM_MAPPING에 enum으로 Stage 모델에서 사용되는 고유한 번호가 포함된 항목을 추가하세요.
  2. PAIRING_RULES 해시에서 해당 이벤트와 호환되는 이벤트를 정의하세요.

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

graph LR; IssueCreated --> IssueClosed; IssueCreated --> IssueFirstAddedToBoard; IssueCreated --> IssueFirstAssociatedWithMilestone; IssueCreated --> IssueFirstMentionedInCommit; IssueCreated --> IssueLastEdited; IssueCreated --> IssueLabelAdded; IssueCreated --> IssueLabelRemoved; ... (이하 생략)

기본 단계

value stream analytics의 원본 구현은 7단계를 정의했습니다. 이러한 단계는 항상 각 부모에 대해 사용할 수 있지만, 이러한 단계를 변경하는 것은 불가능합니다.

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

그 이유는 나중에 단계를 숨기고 정렬하는 기능을 추가하고자 하는 것입니다.

데이터 수집기

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

  • BaseQueryBuilder:
    • 초기 쿼리를 구성하는 역할을 합니다.
    • Stage별 구성: 이벤트 및 쿼리 사용자 정의를 다룹니다.
    • UI에서 오는 매개변수: 날짜 범위.
  • Median: BaseQueryBuilder에서의 쿼리를 사용하여 단계의 중앙값 기간을 계산합니다.
  • RecordsFetcher: BaseQueryBuilder에서의 쿼리 및 가시성 규칙을 적용하기 위해 특정 Finder 클래스를 사용하여 단계에 대한 관련 레코드를 로드합니다.
  • DataForDurationChart: 산점도 차트에 대한 완료 시간(종료 이벤트 타임스탬프)으로 계산된 기간을 로드합니다.

새로운 계산 또는 쿼리를 지원하려면 DataCollector 클래스에 새로운 메서드 호출로 구현하십시오.

집계 된 가치 스트림 분석 백 엔드를 지원하기 위해 이러한 클래스들은 집계 된 이름공간 내에서 다시 구현되었습니다.

데이터베이스 쿼리 백엔드

VSA는 두 가지 백엔드를 지원합니다: 집계 된 및 “실시간”. 실시간 쿼리 백엔드는 언젠가 단계적으로 단곍될 것으로 생각됩니다.

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

고수준 개요

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

프론트엔드

프로젝트 VSA는 모든 사용자에게 제공되며 다음을 포함합니다.

  • 계층에 따라 기술 지표 및 DORA 메트릭의 혼합물을 포함합니다.
  • 기본 단계 세트를 사용합니다.

그룹 VSA는 라이선스가 있는 사용자에게만 제공되며 다음을 포함하여 프로젝트 VSA를 확장합니다.

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

그룹 및 프로젝트 레벨의 VSA 프론트엔드는 둘 다 Vue와 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를 통해 테스트하게 되며 각 테스트 케이스는 다음과 같은 사례를 다루는 여러 테스트로 전환됩니다.

  • 다른 상위 항목: Group 또는 Project
  • 다양한 계산: 중앙값, RecordsFetcher 또는 DataForDurationChart

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

  • 실제 백엔드를 사용하는 종단간 통합 테스트(케이퍼 바라 및 RSpec를 통한).
  • 사전 생성된 데이터 픽스처를 사용한 Jest 프론트엔드 테스트.

개발 환경 설정 및 테스트

Value Stream Analytics를 실행하려면 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

시드 데이터

가치 스트림 분석

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