496 lines
13 KiB
Markdown
496 lines
13 KiB
Markdown
---
|
|
stage: Plan
|
|
group: Optimize
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# Insights for projects **(ULTIMATE)**
|
|
|
|
Configure project insights to explore data such as:
|
|
|
|
- Issues created and closed during a specified period.
|
|
- Average time for merge requests to be merged.
|
|
- Triage hygiene.
|
|
|
|
Insights are also available for [groups](../../group/insights/index.md).
|
|
|
|
## View project insights
|
|
|
|
Prerequisites:
|
|
|
|
- You must have:
|
|
- Access to a project to view information about its merge requests and issues.
|
|
- Permission to view confidential merge requests and issues in the project.
|
|
|
|
To view project insights:
|
|
|
|
1. On the top bar, select **Main menu > Projects** and find your project.
|
|
1. On the left sidebar, select **Analytics > Insights**.
|
|
1. To view a report, select the **Select report** dropdown list.
|
|
|
|
## Configure project insights
|
|
|
|
Prerequisites:
|
|
|
|
- Depending on your project configuration, you must have at least the Developer role.
|
|
|
|
Project insights are configured with the [`.gitlab/insights.yml`](#insights-configuration-file) file in the project. If a project doesn't have a configuration file, it uses the [group configuration](../../group/insights/index.md#configure-group-insights).
|
|
|
|
The `.gitlab/insights.yml` file is a YAML file where you define:
|
|
|
|
- The structure and order of charts in a report.
|
|
- The style of charts displayed in the report of your project or group.
|
|
|
|
To configure project insights, either:
|
|
|
|
- Create a `.gitlab/insights.yml` file locally in the root directory of your project, and push your changes.
|
|
- Create a `.gitlab/insights.yml` file in the UI:
|
|
1. On the top bar, select **Main menu > Projects** and find your project.
|
|
1. Above the file list, select the branch you want to commit to, select the plus icon, then select **New file**.
|
|
1. In the **File name** text box, enter `.gitlab/insights.yml`.
|
|
1. In the large text box, update the file contents.
|
|
1. Select **Commit changes**.
|
|
|
|
After you create the configuration file, you can also
|
|
[use it for the project's group](../../group/insights/index.md#configure-group-insights).
|
|
|
|
## Insights configuration file
|
|
|
|
In the `.gitlab/insights.yml` file:
|
|
|
|
- [Configuration parameters](#insights-configuration-parameters) define the chart behavior.
|
|
- Each report has a unique key and a collection of charts to fetch and display.
|
|
- Each chart definition is made up of a hash composed of key-value pairs.
|
|
|
|
The following example shows a single definition that displays one report with one chart.
|
|
|
|
```yaml
|
|
bugsCharts:
|
|
title: "Charts for bugs"
|
|
charts:
|
|
- title: "Monthly bugs created"
|
|
description: "Open bugs created per month"
|
|
type: bar
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
group_by: month
|
|
period_limit: 24
|
|
```
|
|
|
|
## Insights configuration parameters
|
|
|
|
The following table lists the chart parameters:
|
|
|
|
| Keyword | Description |
|
|
|:---------------------------------------------------|:------------|
|
|
| [`title`](#title) | The title of the chart. This displays on the Insights page. |
|
|
| [`description`](#description) | A description for the individual chart. This displays above the relevant chart. |
|
|
| [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. |
|
|
| [`query`](#query) | A hash that defines the data source and filtering conditions for the chart. |
|
|
|
|
### `title`
|
|
|
|
Use `title` to update the chart title. The title displays on the insights report.
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly bugs created"
|
|
```
|
|
|
|
### `description`
|
|
|
|
Use `description` to add a description of the chart. The description displays above the chart, below the title.
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly bugs created"
|
|
description: "Open bugs created per month"
|
|
```
|
|
|
|
### `type`
|
|
|
|
Use `type` to define the chart type.
|
|
|
|
**Supported values:**
|
|
|
|
| Name | Example: |
|
|
| ----- | ------- |
|
|
| `bar` |  |
|
|
| `bar` (time series, that is when `group_by` is used) |  |
|
|
| `line` |  |
|
|
| `stacked-bar` |  |
|
|
|
|
The `dora` data source supports the `bar` and `line` [chart types](#type).
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly bugs created"
|
|
type: bar
|
|
```
|
|
|
|
### `query`
|
|
|
|
Use `query` to define the data source and filtering conditions for the chart.
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly bugs created"
|
|
description: "Open bugs created per month"
|
|
type: bar
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
collection_labels:
|
|
- S1
|
|
- S2
|
|
- S3
|
|
- S4
|
|
group_by: week
|
|
period_limit: 104
|
|
```
|
|
|
|
The legacy format without the `data_source` parameter is still supported:
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly bugs created"
|
|
description: "Open bugs created per month"
|
|
type: bar
|
|
query:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
collection_labels:
|
|
- S1
|
|
- S2
|
|
- S3
|
|
- S4
|
|
group_by: week
|
|
period_limit: 104
|
|
```
|
|
|
|
#### `query.data_source`
|
|
|
|
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3.
|
|
|
|
Use `data_source` to define the data source that exposes the data.
|
|
|
|
**Supported values:**
|
|
|
|
- `issuables`: Exposes merge request or issue data.
|
|
- `dora`: Exposes DORA metrics.
|
|
|
|
#### `issuable` query parameters
|
|
|
|
##### `query.params.issuable_type`
|
|
|
|
Use `query.params.issuable_type` to define the type of issuable to create a chart for.
|
|
|
|
**Supported values:**
|
|
|
|
- `issue`: The chart displays issues' data.
|
|
- `merge_request`: The chart displays merge requests' data.
|
|
|
|
##### `query.params.issuable_state`
|
|
|
|
Use `query.params.issuable_state` to filter by the current state of the queried issuable.
|
|
|
|
By default, the `opened` state filter is applied.
|
|
|
|
**Supported values:**
|
|
|
|
- `opened`: Open issues or merge requests.
|
|
- `closed`: Closed issues or merge requests.
|
|
- `locked`: Issues or merge requests that have their discussion locked.
|
|
- `merged`: Merged merge requests.
|
|
- `all`: Issues or merge requests in all states.
|
|
|
|
##### `query.params.filter_labels`
|
|
|
|
Use `query.params.filter_labels` to filter by labels applied to the queried issuable.
|
|
|
|
By default, no label filter is applied. All defined labels must
|
|
be applied to the issuable for it to be selected.
|
|
|
|
**Example:**:
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly regressions created"
|
|
type: bar
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
- regression
|
|
```
|
|
|
|
##### `query.params.collection_labels`
|
|
|
|
Use `query.params.collection_labels` to group issuables by the configured labels.
|
|
Grouping is not applied by default.
|
|
|
|
When using this parameter, you must
|
|
set `type` to `line` or `stacked-bar`.
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
weeklyBugsBySeverity:
|
|
title: "Weekly bugs by severity"
|
|
type: stacked-bar
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
collection_labels:
|
|
- S1
|
|
- S2
|
|
- S3
|
|
- S4
|
|
```
|
|
|
|
##### `query.group_by`
|
|
|
|
Use `query.group_by` to define the X-axis of the chart.
|
|
|
|
**Supported values:**
|
|
|
|
- `day`: Group data per day.
|
|
- `week`: Group data per week.
|
|
- `month`: Group data per month.
|
|
|
|
##### `query.period_limit`
|
|
|
|
Use `query.period_limit` to define how far back in time to query issuables (using the `query.period_field`).
|
|
|
|
The unit is related to the value defined in `query.group_by`. For example, if you
|
|
defined `query.group_by: 'day'`, and `query.period_limit: 365`, the chart displays data from the last 365 days.
|
|
|
|
By default, default values are applied depending on the `query.group_by`
|
|
you defined.
|
|
|
|
| `query.group_by` | Default value |
|
|
| ---------------- | ------------- |
|
|
| `day` | 30 |
|
|
| `week` | 4 |
|
|
| `month` | 12 |
|
|
|
|
#### `query.period_field`
|
|
|
|
Use `query.period_field` to define the timestamp field by which to group issuables.
|
|
|
|
**Supported values:**
|
|
|
|
- `created_at` (default): Group data using the `created_at` field.
|
|
- `closed_at`: Group data using the `closed_at` field (for issues only).
|
|
- `merged_at`: Group data using the `merged_at` field (for merge requests only).
|
|
|
|
The `period_field` is automatically set to:
|
|
|
|
- `closed_at` if `query.issuable_state` is `closed`
|
|
- `merged_at` if `query.issuable_state` is `merged`
|
|
- `created_at` otherwise
|
|
|
|
NOTE:
|
|
Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved,
|
|
you may see `created_at` in place of `merged_at`. `created_at` is used instead.
|
|
|
|
#### `DORA` query parameters
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3.
|
|
|
|
Use DORA-specific queries with the `dora` data source to create a DORA chart definition.
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
dora:
|
|
title: "DORA charts"
|
|
charts:
|
|
- title: "DORA deployment frequency"
|
|
type: bar # or line
|
|
query:
|
|
data_source: dora
|
|
params:
|
|
metric: deployment_frequency
|
|
group_by: day
|
|
period_limit: 10
|
|
projects:
|
|
only:
|
|
- 38
|
|
- title: "DORA lead time for changes"
|
|
description: "DORA lead time for changes"
|
|
type: bar
|
|
query:
|
|
data_source: dora
|
|
params:
|
|
metric: lead_time_for_changes
|
|
group_by: day
|
|
environment_tiers:
|
|
- staging
|
|
period_limit: 30
|
|
```
|
|
|
|
##### `query.metric`
|
|
|
|
Use `query.metric` to define the [DORA metrics](../../../api/dora/metrics.md#the-value-field) to query.
|
|
|
|
**Supported values:**
|
|
|
|
- `deployment_frequency` (default)
|
|
- `lead_time_for_changes`
|
|
- `time_to_restore_service`
|
|
- `change_failure_rate`
|
|
|
|
##### `query.group_by`
|
|
|
|
Use `query.group_by` to define the X-axis of your chart.
|
|
|
|
**Supported values:**
|
|
|
|
- `day` (default): Group data per day.
|
|
- `month`: Group data per month.
|
|
|
|
##### `query.period_limit`
|
|
|
|
Use `query.period_limit` to define how far the metrics are queried in the past (default: 15). The maximum period is 180 days or 6 months.
|
|
|
|
##### `query.environment_tiers`
|
|
|
|
Use `query.environment_tiers` to define an array of environments to include the calculation.
|
|
|
|
**Supported values:**
|
|
|
|
- `production`(default)
|
|
- `staging`
|
|
- `testing`
|
|
- `development`
|
|
- `other`
|
|
|
|
### `projects`
|
|
|
|
Use `projects` to limit where issuables are queried from:
|
|
|
|
- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-group-insights), use `projects` to define the projects from which to query issuables. By default, all projects under the group are used.
|
|
- If `.gitlab/insights.yml` is used for a project's insights, specifying other projects does not yield results. By default, the project is used.
|
|
|
|
#### `projects.only`
|
|
|
|
Use `projects.only` to specify the projects from which issuables
|
|
are queried.
|
|
|
|
Projects listed in this parameter are ignored when:
|
|
|
|
- They don't exist.
|
|
- The current user doesn't have sufficient permissions to read them.
|
|
- They are outside the group.
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
monthlyBugsCreated:
|
|
title: "Monthly bugs created"
|
|
description: "Open bugs created per month"
|
|
type: bar
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
projects:
|
|
only:
|
|
- 3 # You can use the project ID
|
|
- groupA/projectA # Or full project path
|
|
- groupA/subgroupB/projectC # Projects in subgroups can be included
|
|
- groupB/project # Projects outside the group will be ignored
|
|
```
|
|
|
|
## Complete insights configuration example
|
|
|
|
```yaml
|
|
.projectsOnly: &projectsOnly
|
|
projects:
|
|
only:
|
|
- 3
|
|
- groupA/projectA
|
|
- groupA/subgroupB/projectC
|
|
|
|
bugsCharts:
|
|
title: "Charts for bugs"
|
|
charts:
|
|
- title: "Monthly bugs created"
|
|
description: "Open bugs created per month"
|
|
type: bar
|
|
<<: *projectsOnly
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
group_by: month
|
|
period_limit: 24
|
|
|
|
- title: "Weekly bugs by severity"
|
|
type: stacked-bar
|
|
<<: *projectsOnly
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: issue
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
collection_labels:
|
|
- S1
|
|
- S2
|
|
- S3
|
|
- S4
|
|
group_by: week
|
|
period_limit: 104
|
|
|
|
- title: "Monthly bugs by team"
|
|
type: line
|
|
<<: *projectsOnly
|
|
query:
|
|
data_source: issuables
|
|
params:
|
|
issuable_type: merge_request
|
|
issuable_state: opened
|
|
filter_labels:
|
|
- bug
|
|
collection_labels:
|
|
- Manage
|
|
- Plan
|
|
- Create
|
|
group_by: month
|
|
period_limit: 24
|
|
```
|