Value Stream Analytics development guide · Gitlab 中文文檔

# Value Stream Analytics development guide > 原文：[https://docs.gitlab.com/ee/development/value_stream_analytics.html](https://docs.gitlab.com/ee/development/value_stream_analytics.html) * [Stage](#stage) * [Events](#events) * [Implementing an `Event` class](#implementing-an-event-class) * [Validating start and end events](#validating-start-and-end-events) * [Parent](#parent) * [How parent relationship it work](#how-parent-relationship-it-work) * [Default stages](#default-stages) * [Data Collector](#data-collector) * [Database query](#database-query) * [High-level overview](#high-level-overview) * [Testing](#testing) # Value Stream Analytics development guide[](#value-stream-analytics-development-guide "Permalink") 值流分析計算域對象上記錄的兩個任意事件之間的時間，并提供有關持續時間的匯總統計信息. 有關如何在 GitLab 中配置 Value Stream Analytics 的信息，請參閱我們的[分析文檔](../user/analytics/value_stream_analytics.html) . ## Stage[](#stage "Permalink") 在開發過程中，會發生一些事件，這些事件會移動問題并在不同的進展階段合并請求，直到認為它們完成為止. 這些階段可以用`Stage`模型表示. 示例階段： * Name: Development * 開始事件：問題已創建 * 結束事件：在提交中首先提到的問題 * Parent: `Group: gitlab-org` ### Events[](#events "Permalink") 事件是價值流分析功能的最小構建塊. 一個階段包括兩個事件： * Start * End 這些事件在持續時間計算中起關鍵作用. Formula: `duration = end_event_time - start_event_time` 為了使持續時間計算更加靈活，每個`Event`都實現為一個單獨的類. 他們負責定義將在計算查詢中使用的時間戳表達式. #### Implementing an `Event` class[](#implementing-an-event-class "Permalink") 有一些方法需要實現， `StageEvent`基類非常詳細地描述了它們. 最重要的是： * `object_type` * `timestamp_projection` `object_type`方法定義將查詢哪個域對象以進行計算. 當前允許兩種模型： * `Issue` * `MergeRequest` 對于持續時間計算，將使用`timestamp_projection`方法. ``` def timestamp_projection # your timestamp expression comes here end # event will use the issue creation time in the duration calculation def timestamp_projection Issue.arel_table[:created_at] end ``` **注意：**也可以使用更復雜的表達式（例如，使用`COALESCE` ）. 查看現有事件類作為示例. 在某些情況下，僅定義`timestamp_projection`方法是不夠的. 計算查詢應該知道哪個表包含時間戳表達式. 每個`Event`類負責修改計算查詢，以使`timestamp_projection`起作用. 這通常意味著加入一個附加表. 連接`issue_metrics`表并使用`first_mentioned_in_commit_at`列作為時間戳表達式的`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) # in this case the query attribute will be based on the Issue model: `Issue.where(...)` query.joins(:metrics) end ``` ### Validating start and end events[](#validating-start-and-end-events "Permalink") 某些開始/結束事件對彼此不"兼容". 例如： * 從"已創建問題"到"已合并請求"：事件類在不同的域模型上定義， `object_type`方法不同. * "問題已關閉"到"問題已創建"：必須先創建問題，然后才能將其關閉. * 從"問題已關閉"到"問題已關閉"：持續時間始終為 0. `StageEvents`模塊描述了允許的`start_event`和`end_event`配對（ `PAIRING_RULES`常數）. 如果添加了新事件，則需要在該模塊中注冊它. 要添加新事件： 1. 在`ENUM_MAPPING`添加一個具有唯一編號的條目，該條目將在`Stage`模型中用作`enum` . 2. 在`PAIRING_RULES`哈希中定義哪些事件與該事件兼容. 支持的開始/結束事件配對：圖 LR; IssueCreated-> IssueClosed; IssueCreated-> IssueFirstAddedToBoard; IssueCreated-> IssueFirstAssociatedWithMilestone; IssueCreated-> IssueFirstMentionedInCommit; IssueCreated-> IssueLastEdited; IssueCreated-> IssueLabelAdded; IssueCreated-> IssueLabelRemoved; MergeRequestCreated-> MergeRequestMerged; MergeRequestCreated-> MergeRequestClosed; MergeRequestCreated-> MergeRequestFirstDeployedToProduction; MergeRequestCreated-> MergeRequestLastBuildStarted; MergeRequestCreated-> MergeRequestLastBuildFinished; MergeRequestCreated-> MergeRequestLastEdited; MergeRequestCreated-> MergeRequestLabelAdded; MergeRequestCreated-> 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; IssueLabelRemoved-> IssueClosed; IssueFirstAddedToBoard-> IssueClosed; IssueFirstAddedToBoard-> IssueFirstAssociatedWithMilestone; IssueFirstAddedToBoard-> IssueFirstMentionedInCommit; IssueFirstAddedToBoard-> IssueLastEdited; IssueFirstAddedToBoard-> IssueLabelAdded; IssueFirstAddedToBoard-> IssueLabelRemoved; IssueFirstAssociatedWithMilestone-> IssueClosed; IssueFirstAssociatedWithMilestone-> IssueFirstAddedToBoard; IssueFirstAssociatedWithMilestone-> IssueFirstMentionedInCommit; IssueFirstAssociatedWithMilestone-> IssueLastEdited; IssueFirstAssociatedWithMilestone-> IssueLabelAdded; IssueFirstAssociatedWithMilestone-> IssueLabelRemoved; IssueFirstMentionedInCommit-> IssueClosed; IssueFirstMentionedInCommit-> IssueFirstAssociatedWithMilestone; IssueFirstMentionedInCommit-> IssueFirstAddedToBoard; IssueFirstMentionedInCommit-> IssueLastEdited; IssueFirstMentionedInCommit-> IssueLabelAdded; IssueFirstMentionedInCommit->已刪除 IssueLabel; 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; MergeRequestLabelRemoved-> MergeRequestLabelAdded; MergeRequestLabelRemoved-> MergeRequestLabelRemoved; ### Parent[](#parent "Permalink") 團隊和組織可能會定義自己的軟件構建方式，因此階段可能完全不同. 對于每個階段，都需要定義一個父對象. 目前支持的父母： * `Project` * `Group` #### How parent relationship it work[](#how-parent-relationship-it-work "Permalink") 1. 用戶導航到價值流分析頁面. 2. 用戶選擇一個組. 3. 后端將加載選定組的已定義階段. 4. 對階段的添加和修改將僅保留在所選組中. ### Default stages[](#default-stages "Permalink") 價值流分析的[原始實施](https://gitlab.com/gitlab-org/gitlab/-/issues/847)定義了 7 個階段. 每個父母都可以使用這些階段，但是無法更改這些階段. 為了提高效率并減少創建的記錄數，默認階段被表示為內存中對象（不持久）. 當用戶首次創建自定義階段時，所有階段都將保留. 此行為在價值流分析服務對象中實現. 這樣做的原因是我們希望稍后添加隱藏和訂購階段的功能. ## Data Collector[](#data-collector "Permalink") `DataCollector`是從數據庫查詢數據的中心點. 該類始終在單個階段上運行，并且由以下組件組成： * `BaseQueryBuilder`: * 負責編寫初始查詢. * 處理特定于`Stage`配置：事件及其查詢自定義. * 來自用戶界面的參數：日期范圍. * `Median` ：使用`BaseQueryBuilder`的查詢計算一個階段的中位數持續時間. * `RecordsFetcher` ：使用來自`BaseQueryBuilder`的查詢和特定的`Finder`類加載階段的相關記錄，以應用可見性規則. * `DataForDurationChart` ：加載散點圖的帶有完成時間（結束事件時間戳）的計算的持續時間. 對于新的計算或查詢，可將其實現為`DataCollector`類中的新方法調用. ## Database query[](#database-query "Permalink") 數據庫查詢的結構： ``` SELECT (customized by: Median or RecordsFetcher or DataForDurationChart) FROM OBJECT_TYPE (Issue or MergeRequest) INNER JOIN (several JOIN statements, depending on the events) WHERE (Filter by the PARENT model, example: filter Issues from Project A) (Date range filter based on the OBJECT_TYPE.created_at) (Check if the START_EVENT is earlier than END_EVENT, preventing negative duration) ``` `Median`的`SELECT`語句的結構： ``` SELECT (calculate median from START_EVENT_TIME-END_EVENT_TIME) ``` 用于`DataForDurationChart`的`SELECT`語句的`DataForDurationChart` ： ``` SELECT (START_EVENT_TIME-END_EVENT_TIME) as duration, END_EVENT.timestamp ``` ## High-level overview[](#high-level-overview "Permalink") * Rails 控制器（ `Analytics::CycleAnalytics`模塊）：值流分析通過 JSON 端點公開其數據，該端點在`analytics`工作區中實現. 配置階段還實現 JSON 端點（CRUD）. * 服務（ `Analytics::CycleAnalytics`模塊）：所有與`Stage`相關的操作都將委派給相應的服務對象. * 模型（ `Analytics::CycleAnalytics`模塊）：模型用于持久化`Stage`對象`ProjectStage`和`GroupStage` . * 要素類（ `Gitlab::Analytics::CycleAnalytics`模塊）： * 負責撰寫查詢并定義特定于功能的業務邏輯. * `DataCollector` ， `Event` ， `StageEvents`等. ## Testing[](#testing "Permalink") 由于我們有很多事件和可能的配對，因此無法測試每個配對. 規則是至少要有一個使用`Event`類的測試用例. 使用新`Event`為階段編寫測試用例可能會遇到挑戰，因為必須為兩個事件都創建數據. 為了使此過程更簡單，必須在`data_collector_spec.rb`中實現每個測試用例，在該`data_collector_spec.rb`中，通過`DataCollector`對該階段進行測試. 每個測試用例都將變成多個測試，涵蓋以下情況： * 不同的父母： `Group`或`Project` * 不同的計算方式： `Median` ， `RecordsFetcher`或`DataForDurationChart`