summaryrefslogtreecommitdiff
path: root/doc/user/analytics/value_stream_analytics.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/analytics/value_stream_analytics.md')
-rw-r--r--doc/user/analytics/value_stream_analytics.md316
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:
-![Value stream analytics filter bar](img/project_vsa_filter_v14_3.png "Active filter bar for a project's value stream analytics")
+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:
-![Value stream analytics stage table](img/project_vsa_stage_table_v14_4.png "Project VSA stage table")
+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).