diff options
Diffstat (limited to 'doc/user/analytics/value_stream_analytics.md')
| -rw-r--r-- | doc/user/analytics/value_stream_analytics.md | 316 |
1 files changed, 149 insertions, 167 deletions
diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 6bad374c371..92c4d447ed9 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -10,215 +10,197 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab Premium 12.3 at the group level. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from cycle analytics to value stream analytics in GitLab 12.8. -Value stream analytics measures the time spent to go from an -[idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) -(also known as cycle time) for each of your projects or groups. Value stream analytics displays the median time -spent in each stage defined in the process. +Value stream analytics provides metrics about each stage of your software development process. -You can use value stream analytics to determine the velocity of a given -project. It points to bottlenecks in the development process, enabling management -to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. +Use value stream analytics to identify: -For information about how to contribute to the development of value stream analytics, see our [contributor documentation](../../development/value_stream_analytics.md). +- The amount of time it takes to go from an idea to production. +- The velocity of a given project. +- Bottlenecks in the development process. +- Factors that cause your software development lifecycle to slow down. -To access value stream analytics for a project: +Value stream analytics is also available for [groups](../group/value_stream_analytics). -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. - -NOTE: -[Value stream analytics for groups](../group/value_stream_analytics) is also available. - -## Default stages +## View value stream analytics -The stages tracked by value stream analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). You can customize these stages in value stream analytics for groups. +> - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 +> - Sorting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. -- **Issue** (Tracker) - - Time to schedule an issue (by milestone or by adding it to an issue board) -- **Plan** (Board) - - Time to first commit -- **Code** (IDE) - - Time to create a merge request -- **Test** (CI) - - Time it takes GitLab CI/CD to test your code -- **Review** (Merge request) - - Time spent on code review -- **Staging** (Continuous Deployment) - - Time between merging and deploying to production +To view value stream analytics for your project: -## Filter value stream analytics data +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. To view metrics for each stage, above the **Filter results** text box, select a stage. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. Optional. Sort results by ascending or descending: + - To sort by most recent or oldest workflow item, select the **Merge requests** or **Issues** + header. The header name differs based on the stage you select. + - To sort by most or least amount of time spent in each stage, select the **Time** header. + +The table shows a list of related workflow items for the selected stage. Based on the stage you choose, this can be: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 +- CI/CD jobs +- Issues +- Merge requests +- Pipelines -You can filter analytics based on the following parameters: +A badge next to the workflow items table header shows the number of workflow items that completed the selected stage. -- Milestones (Group level) -- Labels (Group level) -- Author -- Assignees +## View time spent in each development stage -To filter results: +Value stream analytics shows the median time spent by issues or merge requests in each development stage. -1. Select the **Filter results** text box. -1. Select a parameter. -1. Select a value. To find a value in the list, enter the value name. +To view the median time spent in each stage: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. To view the median time for each stage, above the **Filter results** text box, point to a stage. -### Date ranges +## View the lead time and cycle time for issues -To filter analytics results based on a date range, -select different **From** and **To** days -from the date picker (default: last 30 days). +Value stream analytics shows the lead time and cycle time for issues in your project: -### Stage table +- Lead time: Median time from when the issue was created to when it was closed. +- Cycle time: Median time from first commit to issue closed. Commits are associated with issues when users [cross-link them in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages). -> Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. +To view the lead time and cycle time for issues: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -The stage table shows a list of related workflow items for the selected stage. This can include: +The **Lead Time** and **Cycle Time** metrics display below the **Filter results** text box. -- CI/CD jobs -- Issues -- Merge requests -- Pipelines +## View lead time for changes for merge requests **(ULTIMATE)** -A little badge next to the workflow items table header shows the number of workflow items that -completed the selected stage. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. -The stage table also includes the **Time** column, which shows how long it takes each item to pass -through the selected value stream stage. +Lead time for changes is the median duration between when a merge request is merged and when it's deployed to production. -To sort the stage table by a table column, select the table header. -You can sort in ascending or descending order. To find items that spent the most time in a stage, -potentially causing bottlenecks in your value stream, sort the table by the **Time** column. -From there, select individual items to drill in and investigate how delays are happening. -To see which items most recently exited the stage, sort by the work item column on the left. +To view the lead time for changes for merge requests in your project: -The table displays 20 items per page. If there are more than 20 items, you can use the -**Prev** and **Next** buttons to navigate through the pages. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -## How Time metrics are measured +The **Lead Time for Changes** metrics display below the **Filter results** text box. -The **Time** metrics near the top of the page are measured as follows: +## View number of successful deployments **(PREMIUM)** -- **Lead time**: Median time from issue created to issue closed. -- **Cycle time**: Median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages).) -- **Lead Time for Changes**: median duration between merge request merge and deployment to a production environment for all MRs deployed in the given time period. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5 (Ultimate only). +To view deployment metrics, you must have a +[production environment configured](../../ci/environments/index.md#deployment-tier-of-environments). -## Deployment metrics (**PREMIUM**) +Value stream analytics shows the following deployment metrics for your project: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) in GitLab 11.3. +- Deploys: The number of successful deployments in the date range. +- Deployment Frequency: The average number of successful deployments per day in the date range. -Value stream analytics exposes two deployment related metrics near the top of the page: +To view deployment metrics for your project: -- **Deploys:** The number of successful deployments in the date range. -- **Deployment Frequency:** The average number of successful deployments. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -The deployment metrics calculation uses the same method as the -[value stream analytics for groups](../group/value_stream_analytics/index.md#how-metrics-are-measured). -Both of them are based on the [DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). +The **Deploys** and **Deployment Frequency** metrics display below the **Filter results** text box. -## How the stages are measured +Deployment metrics are calculated based on data from the +[DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). -Value stream analytics uses start events and end events to measure the time that an issue or merge request spends in each stage. -For example, a stage might start when one label is added to an issue and end when another label is added. -Items aren't included in the stage time calculation if they have not reached the end event. +NOTE: +In GitLab 13.9 and later, metrics are calculated based on when the deployment was finished. +In GitLab 13.8 and earlier, metrics are calculated based on when the deployment was created. -| Stage | Description | -|---------|---------------| -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | -| Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | -| Review | Measures the median time taken to review merge requests with a closing issue pattern, from creation to merge. | -| Staging | Measures the median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](#how-the-production-environment-is-identified). Data not collected without a production environment. | +## Access permissions for value stream analytics -How this works: +Access permissions for value stream analytics depend on the project type. -1. Issues and merge requests are grouped in pairs, where the merge request has the - [closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - for the corresponding issue. Issue and merge request pairs without closing patterns are - not included. -1. Issue and merge request pairs are filtered by the last XX days, specified through the UI - (default is `90` days). Pairs outside the filtered range are not included. -1. For the remaining pairs, review information needed for stages, including - issue creation date and merge request merge time. +| Project type | Permissions | +|--------------|----------------------------------------| +| Public | Anyone can access. | +| Internal | Any authenticated user can access. | +| Private | Any member Guest and above can access. | -In short, the value stream analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: +## How value stream analytics measures each stage -- Merge requests that do not close an issue. -- Issues that do not include labels present in the issue board. -- Issues without a milestone. -- Staging stages, in projects without a [production environment](#how-the-production-environment-is-identified). +Value stream analytics uses start and end events to measure the time that an issue or merge request +spends in each stage. -## How the production environment is identified +For example, a stage might start when a user adds a label to an issue, and ends when they add another label. +Items aren't included in the stage time calculation if they have not reached the end event. -Value stream analytics identifies production environments based on the -[deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). +| Stage | Measurement method | +|---------|----------------------| +| Issue | The median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) that has been created for the label. | +| Plan | The median time between the action you took for the previous stage, and when you push the first commit to the branch. The first branch commit triggers the transition from **Plan** to **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is not included in a commit, that data is not included in the measurement time of the stage. | +| Code | The median time between pushing a first commit (previous stage) and creating a merge request. The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, `xxx` is the issue number for the merge request. If there is no closing pattern, the start time is set to the create time of the first commit. | +| Test | The time from start to finish for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | +| Review | The median time taken to review merge requests with a closing issue pattern, from creation to merge. | +| Staging | The median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). Data is not collected without a production environment. | ## Example workflow -Here's a fictional workflow of a single cycle that happens in a -single day, passing through all seven stages. If a stage doesn't have -a start and a stop mark, it isn't measured and hence isn't calculated in the median -time. It's assumed that milestones are created, and CI for testing and setting -environments is configured. - -1. Issue is created at 09:00 (start of **Issue** stage). -1. Issue is added to a milestone at 11:00 (stop of **Issue** stage and start of - **Plan** stage). -1. Start working on the issue, create a branch locally, and make one commit at - 12:00. -1. Make a second commit to the branch that mentions the issue number at 12:30 - (stop of **Plan** stage and start of **Code** stage). -1. Push branch, and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - in its description at 14:00 (stop of **Code** stage and start of **Test** and - **Review** stages). -1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/index.md) and - takes 5 minutes (stop of **Test** stage). -1. Review merge request, ensure that everything is okay, and then merge the merge - request at 19:00 (stop of **Review** stage and start of **Staging** stage). -1. The merge request is merged, and a deployment to the `production` - environment starts and finishes at 19:30 (stop of **Staging** stage). - -From the previous example we see the time used for each stage: - -- **Issue**: 2 hrs (09:00 to 11:00) -- **Plan**: 1 hr (11:00 to 12:00) -- **Code**: 2 hrs (12:00 to 14:00) +This example shows a workflow through all seven stages in one day. In this +example, milestones have been created and CI for testing and setting environments is configured. + +- 09:00: Create issue. **Issue** stage starts. +- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally. +**Issue** stage stops and **Plan** stage starts. +- 12:00: Make the first commit. +- 12:30: Make the second commit to the branch that mentions the issue number. **Plan** stage stops and **Code** stage starts. +- 14:00: Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically). **Code** stage stops and **Test** and **Review** stages start. +- The CI takes 5 minutes to run scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/index.md). +**Test** stage stops. +- Review merge request. +- 19:00: Merge the merge request. **Review** stage stops and **Staging** stage starts. +- 19:30: Deployment to the `production` environment starts and finishes. **Staging** stops. + +Value stream analytics records the following times for each stage: + +- **Issue**: 09:00 to 11:00: 2 hrs +- **Plan**: 11:00 to 12:00: 1 hr +- **Code**: 12:00 to 14:00: 2 hrs - **Test**: 5 minutes -- **Review**: 5 hrs (14:00 to 19:00) -- **Staging**: 30 minutes (19:00 to 19:30) - -More information: - -- Although the previous example specifies the issue number in a later commit, the process - still collects analytics data for the issue. -- The time required in the **Test** stage isn't included in the overall time of - the cycle. The time is included in the **Review** process, as every merge request should be - tested. -- The previous example illustrates only one cycle of the multiple stages. Value - stream analytics, on its dashboard, shows the calculated median elapsed time - for these issues. - -## Permissions - -The permissions for the value stream analytics for projects dashboard include: - -| Project type | Permissions | -|--------------|---------------------------------------| -| Public | Anyone can access | -| Internal | Any authenticated user can access | -| Private | Any member Guest and above can access | - -You can [read more about permissions](../../user/permissions.md) in general. - -## More resources - -Learn more about value stream analytics with the following resources: - -- [Value stream analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -- [Value stream analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). -- [Value stream analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). +- **Review**: 14:00 to 19:00: 5 hrs +- **Staging**: 19:00 to 19:30: 30 minutes + +There are some additional considerations for this example: + +- Although this example specifies the issue number in a later commit, the process +still collects analytics data for the issue. +- The time required in the **Test** stage is included in the **Review** process, +as every merge request should be tested. +- This example illustrates only one cycle of multiple stages. The value +stream analytics dashboard shows the calculated median elapsed time for these issues. +- Value stream analytics identifies production environments based on the +[deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). |