2020-05-05 17:09:42 -04:00
---
stage: Manage
2020-11-19 13:09:13 -05:00
group: Optimize
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-05 17:09:42 -04:00
---
2022-01-12 13:13:20 -05:00
# Value stream analytics for projects **(FREE)**
2020-02-07 16:08:39 -05:00
2022-01-12 13:13:20 -05:00
> - Introduced as cycle analytics prior to GitLab 12.3 at the project level.
2021-05-27 14:10:52 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab Premium 12.3 at the group level.
2022-01-12 13:13:20 -05:00
> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from cycle analytics to value stream analytics in GitLab 12.8.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
Value stream analytics provides metrics about each stage of your software development process.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
Use value stream analytics to identify:
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
- 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.
2020-09-28 14:09:40 -04:00
2022-02-18 16:15:49 -05:00
Value stream analytics is also available for [groups ](../group/value_stream_analytics ).
2022-01-12 13:13:20 -05:00
2022-02-18 16:15:49 -05:00
## View value stream analytics
2021-10-12 02:09:42 -04:00
2022-02-18 16:15:49 -05:00
> - 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.
2021-10-12 02:09:42 -04:00
2022-02-18 16:15:49 -05:00
To view value stream analytics for your project:
2021-10-12 02:09:42 -04:00
2022-02-18 16:15:49 -05:00
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:
2021-10-12 11:12:08 -04:00
- CI/CD jobs
- Issues
- Merge requests
- Pipelines
2022-02-18 16:15:49 -05:00
A badge next to the workflow items table header shows the number of workflow items that completed the selected stage.
2021-10-12 11:12:08 -04:00
2022-02-18 16:15:49 -05:00
## View time spent in each development stage
2021-10-12 11:12:08 -04:00
2022-02-18 16:15:49 -05:00
Value stream analytics shows the median time spent by issues or merge requests in each development stage.
2021-10-12 11:12:08 -04:00
2022-02-18 16:15:49 -05:00
To view the median time spent in each stage:
2021-10-12 11:12:08 -04:00
2022-02-18 16:15:49 -05:00
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.
2022-02-24 04:14:06 -05:00
2022-02-18 16:15:49 -05:00
## View the lead time and cycle time for issues
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
Value stream analytics shows the lead time and cycle time for issues in your project:
2020-05-26 20:08:11 -04:00
2022-02-18 16:15:49 -05:00
- 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 ).
2021-12-01 04:10:25 -05:00
2022-02-18 16:15:49 -05:00
To view the lead time and cycle time for issues:
2021-12-01 04:10:25 -05:00
2022-02-18 16:15:49 -05:00
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.
2021-12-01 04:10:25 -05:00
2022-02-18 16:15:49 -05:00
The **Lead Time** and **Cycle Time** metrics display below the **Filter results** text box.
2021-12-01 04:10:25 -05:00
2022-02-18 16:15:49 -05:00
## View lead time for changes for merge requests **(ULTIMATE)**
2021-12-01 04:10:25 -05:00
2022-02-18 16:15:49 -05:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5.
2020-05-26 20:08:11 -04:00
2022-02-18 16:15:49 -05:00
Lead time for changes is the median duration between when a merge request is merged and when it's deployed to production.
2020-05-26 20:08:11 -04:00
2022-02-18 16:15:49 -05:00
To view the lead time for changes for merge requests in your project:
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
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.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
The **Lead Time for Changes** metrics display below the **Filter results** text box.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
## View number of successful deployments **(PREMIUM)**
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
To view deployment metrics, you must have a
[production environment configured ](../../ci/environments/index.md#deployment-tier-of-environments ).
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
Value stream analytics shows the following deployment metrics for your project:
2022-02-24 04:14:06 -05:00
2022-02-18 16:15:49 -05:00
- Deploys: The number of successful deployments in the date range.
- Deployment Frequency: The average number of successful deployments per day in the date range.
2020-10-16 17:09:08 -04:00
2022-02-18 16:15:49 -05:00
To view deployment metrics for your project:
2020-10-16 17:09:08 -04:00
2022-02-18 16:15:49 -05:00
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.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
The **Deploys** and **Deployment Frequency** metrics display below the **Filter results** text box.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
Deployment metrics are calculated based on data from the
[DORA API ](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api ).
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
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.
2020-03-18 17:09:22 -04:00
2022-02-18 16:15:49 -05:00
## Access permissions for value stream analytics
2020-04-21 11:21:10 -04:00
2022-02-18 16:15:49 -05:00
Access permissions for value stream analytics depend on the project type.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
| Project type | Permissions |
|--------------|----------------------------------------|
| Public | Anyone can access. |
| Internal | Any authenticated user can access. |
| Private | Any member Guest and above can access. |
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
## How value stream analytics measures each stage
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
Value stream analytics uses start and end events to measure the time that an issue or merge request
spends in each stage.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
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.
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
| 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. |
2020-02-07 16:08:39 -05:00
2022-02-18 16:15:49 -05:00
## Example workflow
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.
2022-02-24 04:14:06 -05:00
- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally.
**Issue** stage stops and **Plan** stage starts.
2022-02-18 16:15:49 -05:00
- 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.
2022-02-24 04:14:06 -05:00
- The CI takes 5 minutes to run scripts defined in [`.gitlab-ci.yml` ](../../ci/yaml/index.md ).
2022-02-18 16:15:49 -05:00
**Test** stage stops.
2022-02-24 04:14:06 -05:00
- Review merge request.
2022-02-18 16:15:49 -05:00
- 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
2022-02-24 04:14:06 -05:00
- **Review**: 14:00 to 19:00: 5 hrs
2022-02-18 16:15:49 -05:00
- **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.
2022-02-24 04:14:06 -05:00
- Value stream analytics identifies production environments based on the
2022-02-18 16:15:49 -05:00
[deployment tier of environments ](../../ci/environments/index.md#deployment-tier-of-environments ).