가치 흐름 분석 개발 지침

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

가치 흐름 분석은 어떻게 작동하나요?

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

예를 들어:

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

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

  • 집계: 중앙값, 평균
  • 목록: 개별 병합 요청 및 이슈 기록에 대한 기간 나열

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

기능 가용성

  • 그룹 수준(라이센스 필요): Ultimate 또는 Premium 구독이 필요합니다. 이 버전은 가장 많은 기능을 포함합니다.

  • 프로젝트 수준(라이센스 필요): 프로젝트 수준 VSA에 기능을 계속 추가하여 그룹 수준 VSA에 맞추고 있습니다.

  • 프로젝트 수준(FOSS): 기본 상태를 유지합니다.

기능 그룹 수준(라이센스 필요) 프로젝트 수준(라이센스 필요) 프로젝트 수준(FOSS)
사용자 정의 가치 흐름 생성 예 아니요, 기본 단계가 포함된 하나의 가치 흐름(기본값)만 존재 아니요, 기본 단계가 포함된 하나의 가치 흐름(기본값)만 존재
사용자 정의 단계 생성 예 아니요 아니요
필터링(작성자, 레이블, 마일스톤 등) 예 예 예
단계 시간 차트 예 아니요 아니요
총 시간 차트 예 아니요 아니요
유형별 작업 차트 예 아니요 아니요
DORA 메트릭 예 예 아니요
주기 시간 및 리드 타임 요약(수명 주기 메트릭) 예 예 아니요
새 이슈, 커밋 및 배포(수명 주기 메트릭) 예, 커밋 제외 예 예
집계된 백엔드 사용 예 아니요 아니요
날짜 필터 동작 날짜 범위 내에서 완료된 항목 필터 생성 날짜로 항목 필터. 생성 날짜로 항목 필터.
권한 최소 작성자 최소 작성자 공용 가능.

VSA 핵심 도메인 객체

단계

단계는 추가 메타데이터(단계의 이름 등)와 함께 이벤트 쌍(시작 및 종료 이벤트)을 나타냅니다. 단계는 백엔드에서 정의된 쌍 규칙 내에서 사용자가 구성할 수 있습니다.

예제 단계: 코드 검토

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

역사적으로, 가치 흐름 분석은 사용자의 구독에 관계없이 항상 사용 가능한 여섯 단계를 정의했습니다.

가치 흐름

가치 흐름은 단계의 컨테이너 객체입니다. DevOps 수명 주기의 다양한 측면에 집중하는 여러 가치 흐름이 그룹당 있을 수 있습니다.

이벤트

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

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

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

공식: duration = end_event_time - start_event_time

기간 계산을 유연하게 만들기 위해, 각 Event는 별도의 클래스로 구현됩니다.

이들은 계산 쿼리에서 사용되는 타임스탬프 표현을 정의하는 책임이 있습니다.

Event 클래스 구현

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

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

graph LR; IssueCreated --> IssueClosed; IssueCreated --> IssueFirstAddedToBoard; IssueCreated --> IssueFirstAssociatedWithMilestone; IssueCreated --> IssueFirstMentionedInCommit; IssueCreated --> IssueLastEdited; IssueCreated --> IssueLabelAdded; IssueCreated --> IssueLabelRemoved; IssueCreated --> IssueFirstAssignedAt; MergeRequestCreated --> MergeRequestMerged; MergeRequestCreated --> MergeRequestClosed; MergeRequestCreated --> MergeRequestFirstDeployedToProduction; MergeRequestCreated --> MergeRequestLastBuildStarted; MergeRequestCreated --> MergeRequestLastBuildFinished; MergeRequestCreated --> MergeRequestLastEdited; MergeRequestCreated --> MergeRequestLabelAdded; MergeRequestCreated --> MergeRequestLabelRemoved; MergeRequestCreated --> MergeRequestFirstAssignedAt; MergeRequestFirstAssignedAt --> MergeRequestClosed; MergeRequestFirstAssignedAt --> MergeRequestLastBuildStarted; MergeRequestFirstAssignedAt --> MergeRequestLastEdited; MergeRequestFirstAssignedAt --> MergeRequestMerged; MergeRequestFirstAssignedAt --> MergeRequestLabelAdded; MergeRequestFirstAssignedAt --> MergeRequestLabelRemoved; MergeRequestLastBuildStarted --> MergeRequestLastBuildFinished; MergeRequestLastBuildStarted --> MergeRequestClosed; MergeRequestLastBuildStarted --> MergeRequestFirstDeployedToProduction; MergeRequestLastBuildStarted --> MergeRequestLastEdited; MergeRequestLastBuildStarted --> MergeRequestMerged; MergeRequestLastBuildStarted --> MergeRequestLabelAdded; MergeRequestLastBuildStarted --> MergeRequestLabelRemoved; MergeRequestMerged --> MergeRequestFirstDeployedToProduction; MergeRequestMerged --> MergeRequestClosed; MergeRequestMerged --> MergeRequestFirstDeployedToProduction; MergeRequestMerged --> MergeRequestLastEdited; MergeRequestMerged --> MergeRequestLabelAdded; MergeRequestMerged --> MergeRequestLabelRemoved; IssueLabelAdded --> IssueLabelAdded; IssueLabelAdded --> IssueLabelRemoved; IssueLabelAdded --> IssueClosed; IssueLabelAdded --> IssueFirstAssignedAt; IssueLabelRemoved --> IssueClosed; IssueLabelRemoved --> IssueFirstAssignedAt; IssueFirstAddedToBoard --> IssueClosed; IssueFirstAddedToBoard --> IssueFirstAssociatedWithMilestone; IssueFirstAddedToBoard --> IssueFirstMentionedInCommit; IssueFirstAddedToBoard --> IssueLastEdited; IssueFirstAddedToBoard --> IssueLabelAdded; IssueFirstAddedToBoard --> IssueLabelRemoved; IssueFirstAddedToBoard --> IssueFirstAssignedAt; IssueFirstAssignedAt --> IssueClosed; IssueFirstAssignedAt --> IssueFirstAddedToBoard; IssueFirstAssignedAt --> IssueFirstAssociatedWithMilestone; IssueFirstAssignedAt --> IssueFirstMentionedInCommit; IssueFirstAssignedAt --> IssueLastEdited; IssueFirstAssignedAt --> IssueLabelAdded; IssueFirstAssignedAt --> IssueLabelRemoved; IssueFirstAssociatedWithMilestone --> IssueClosed; IssueFirstAssociatedWithMilestone --> IssueFirstAddedToBoard; IssueFirstAssociatedWithMilestone --> IssueFirstMentionedInCommit; IssueFirstAssociatedWithMilestone --> IssueLastEdited; IssueFirstAssociatedWithMilestone --> IssueLabelAdded; IssueFirstAssociatedWithMilestone --> IssueLabelRemoved; IssueFirstAssociatedWithMilestone --> IssueFirstAssignedAt; IssueFirstMentionedInCommit --> IssueClosed; IssueFirstMentionedInCommit --> IssueFirstAssociatedWithMilestone; IssueFirstMentionedInCommit --> IssueFirstAddedToBoard; IssueFirstMentionedInCommit --> IssueLastEdited; IssueFirstMentionedInCommit --> IssueLabelAdded; IssueFirstMentionedInCommit --> IssueLabelRemoved; IssueClosed --> IssueLastEdited; IssueClosed --> IssueLabelAdded; IssueClosed --> IssueLabelRemoved; MergeRequestClosed --> MergeRequestFirstDeployedToProduction; MergeRequestClosed --> MergeRequestLastEdited; MergeRequestClosed --> MergeRequestLabelAdded; MergeRequestClosed --> MergeRequestLabelRemoved; MergeRequestFirstDeployedToProduction --> MergeRequestLastEdited; MergeRequestFirstDeployedToProduction --> MergeRequestLabelAdded; MergeRequestFirstDeployedToProduction --> MergeRequestLabelRemoved; MergeRequestLastBuildFinished --> MergeRequestClosed; MergeRequestLastBuildFinished --> MergeRequestFirstDeployedToProduction; MergeRequestLastBuildFinished --> MergeRequestLastEdited; MergeRequestLastBuildFinished --> MergeRequestMerged; MergeRequestLastBuildFinished --> MergeRequestLabelAdded; MergeRequestLastBuildFinished --> MergeRequestLabelRemoved; MergeRequestLabelAdded --> MergeRequestLabelAdded; MergeRequestLabelAdded --> MergeRequestLabelRemoved; MergeRequestLabelAdded --> MergeRequestMerged; MergeRequestLabelAdded --> MergeRequestFirstAssignedAt; MergeRequestLabelRemoved --> MergeRequestLabelAdded; MergeRequestLabelRemoved --> MergeRequestLabelRemoved; MergeRequestLabelRemoved --> MergeRequestFirstAssignedAt;

기본 단계

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

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

이유는 이후에 단계를 숨기고 순서를 조정할 수 있는 기능을 추가하고 싶었기 때문입니다.

데이터 수집기

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

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

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

집계된 가치 흐름 분석 백엔드를 지원하기 위해 이러한 클래스는 Aggregated 네임스페이스 내에서 재구현되었습니다.

데이터베이스 쿼리 백엔드

VSA는 두 개의 백엔드를 지원합니다: aggregated 및 “live”. 라이브 쿼리 백엔드는 레거시로 간주될 수 있으며, 언젠가는 단계적으로 지원 중단될 예정입니다.

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

고수준 개요

  • 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 모듈을 활용합니다.

공유 구성 요소

UI의 일부는 프로젝트 VSA와 그룹 VSA 간에 공유됩니다. 예를 들어 스테이지 테이블과 경로입니다.

이 공유 구성 요소는 프로젝트 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 프론트엔드 테스트.

개발 설정 및 테스트

Value Stream Analytics를 실행하려면 GDK를 사용할 수 있습니다. 기본적으로 기능의 프로젝트 수준(FOSS) 버전을 볼 수 있습니다.

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

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

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

이 단계 후, 그룹 수준의 가치 흐름 분석 페이지에 액세스할 수 있으며, 여기서 가치 흐름과 스테이지를 생성할 수 있습니다. 데이터 집계는 지연될 수 있으므로 스테이지 생성 직후에 데이터를 볼 수 없을 수 있습니다. 이 프로세스를 가속화하려면 Rails 콘솔(rails c)에서 다음 명령을 실행할 수 있습니다:

Analytics::CycleAnalytics::ReaggregationWorker.new.perform

시드 데이터

가치 흐름 분석

가치 흐름 분석을 위한 데이터 시딩 방법에 대한 설명은 개발 시드 파일을 참조하세요.