diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-30 12:09:43 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-30 12:09:43 +0300 |
commit | 14846d722eb52ea70bc3092eb5da80ce1c2e9750 (patch) | |
tree | 34700bc9c8c7cddbf955bc079a174ca75e099903 /doc/user/project/insights | |
parent | bfb305ef516d8d6c07e91024a16772070d09afe0 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user/project/insights')
-rw-r--r-- | doc/user/project/insights/index.md | 141 |
1 files changed, 75 insertions, 66 deletions
diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 1107e91c33e..8e08d82c067 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -95,8 +95,9 @@ The following table lists the chart parameters: ### `title` -`title` is the title of the chart as it displays on the Insights page. -For example: +Use `title` to update the chart title. The title displays on the insights report. + +**Example:** ```yaml monthlyBugsCreated: @@ -105,8 +106,9 @@ monthlyBugsCreated: ### `description` -The `description` text is displayed above the chart, but below the title. It's used -to give extra details regarding the chart, for example: +Use `description` to add a description of the chart. The description displays above the chart, below the title. + +**Example:** ```yaml monthlyBugsCreated: @@ -116,33 +118,32 @@ monthlyBugsCreated: ### `type` -`type` is the chart type. +Use `type` to define the chart type. -For example: +**Supported values:** -```yaml -monthlyBugsCreated: - title: "Monthly bugs created" - type: bar -``` - -Supported values are: - -| Name | Example | +| Name | Example: | | ----- | ------- | | `bar` | ![Insights example bar chart](img/insights_example_bar_chart.png) | | `bar` (time series, that is when `group_by` is used) | ![Insights example bar time series chart](img/insights_example_bar_time_series_chart.png) | | `line` | ![Insights example stacked bar chart](img/insights_example_line_chart.png) | | `stacked-bar` | ![Insights example stacked bar chart](img/insights_example_stacked_bar_chart.png) | -NOTE: -The `dora` data source supports the `bar` and `line` chart types. +The `dora` data source supports the `bar` and `line` [chart types](#type). + +**Example:** + +```yaml +monthlyBugsCreated: + title: "Monthly bugs created" + type: bar +``` ### `query` -`query` allows to define the data source and various filtering conditions for the chart. +Use `query` to define the data source and filtering conditions for the chart. -Example: +**Example:** ```yaml monthlyBugsCreated: @@ -190,46 +191,46 @@ monthlyBugsCreated: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3. -The `data_source` parameter was introduced to allow visualizing data from different data sources. +Use `data_source` to define the data source that exposes the data. -Supported values are: +**Supported values:** - `issuables`: Exposes merge request or issue data. -- `dora`: Exposes DORA metrics data. +- `dora`: Exposes DORA metrics. -#### `Issuable` query parameters +#### `issuable` query parameters ##### `query.params.issuable_type` -Defines the type of "issuable" you want to create a chart for. +Use `query.params.issuable_type` to define the type of issuable to create a chart for. -Supported values are: +**Supported values:** - `issue`: The chart displays issues' data. - `merge_request`: The chart displays merge requests' data. ##### `query.params.issuable_state` -Filter by the current state of the queried "issuable". +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 are: +**Supported values:** -- `opened`: Open issues / merge requests. -- `closed`: Closed Open issues / merge requests. -- `locked`: Issues / merge requests that have their discussion locked. +- `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 / merge requests in all states +- `all`: Issues or merge requests in all states. ##### `query.params.filter_labels` -Filter by labels currently applied to the queried "issuable". +Use `query.params.filter_labels` to filter by labels applied to the queried issuable. -By default, no labels filter is applied. All the defined labels must be -currently applied to the "issuable" in order for it to be selected. +By default, no label filter is applied. All defined labels must +be applied to the issuable for it to be selected. -Example: +**Example:**: ```yaml monthlyBugsCreated: @@ -247,12 +248,13 @@ monthlyBugsCreated: ##### `query.params.collection_labels` -Group "issuable" by the configured labels. +Use `query.params.collection_labels` to group issuables by the configured labels. +Grouping is not applied by default. -By default, no grouping is done. When using this keyword, you need to -set `type` to either `line` or `stacked-bar`. +When using this parameter, you must +set `type` to `line` or `stacked-bar`. -Example: +**Example:** ```yaml weeklyBugsBySeverity: @@ -274,9 +276,9 @@ weeklyBugsBySeverity: ##### `query.group_by` -Define the X-axis of your chart. +Use `query.group_by` to define the X-axis of the chart. -Supported values are: +**Supported values:** - `day`: Group data per day. - `week`: Group data per week. @@ -284,11 +286,10 @@ Supported values are: ##### `query.period_limit` -Define how far "issuables" are queried in the past (using the `query.period_field`). +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 `query.group_by` you defined. For instance if you -defined `query.group_by: 'day'` then `query.period_limit: 365` would mean -"Gather and display data for the last 365 days". +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. @@ -301,9 +302,9 @@ you defined. #### `query.period_field` -Define the timestamp field used to group "issuables". +Use `query.period_field` to define the timestamp field by which to group issuables. -Supported values are: +**Supported values:** - `created_at` (default): Group data using the `created_at` field. - `closed_at`: Group data using the `closed_at` field (for issues only). @@ -323,7 +324,9 @@ you may see `created_at` in place of `merged_at`. `created_at` is used instead. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3. -An example DORA chart definition: +Use DORA-specific queries with the `dora` data source to create a DORA chart definition. + +**Example:** ```yaml dora: @@ -355,53 +358,59 @@ dora: ##### `query.metric` -Defines which DORA metric to query. The available values are: +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` -The metrics are described on the [DORA API](../../../api/dora/metrics.md#the-value-field) page. - ##### `query.group_by` -Define the X-axis of your chart. +Use `query.group_by` to define the X-axis of your chart. -Supported values are: +**Supported values:** - `day` (default): Group data per day. - `month`: Group data per month. ##### `query.period_limit` -Define how far the metrics are queried in the past (default: 15). Maximum lookback period is 180 days or 6 months. +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` -An array of environments to include into the calculation (default: production). Available options: `production`, `staging`, `testing`, `development`, `other`. +Use `query.environment_tiers` to define an array of environments to include the calculation. + +**Supported values:** + +- `production`(default) +- `staging` +- `testing` +- `development` +- `other` ### `projects` -You can limit where the "issuables" can be queried from: +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-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects currently under the group are used. -- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-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` -The `projects.only` option specifies the projects which the "issuables" -should be queried from. +Use `projects.only` to specify the projects from which issuables +are queried. -Projects listed here are ignored when: +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 of the group. +- They are outside the group. -In the following `insights.yml` example, we specify the projects -the queries are used on. This example is useful when setting -a group's insights: +**Example:** ```yaml monthlyBugsCreated: @@ -423,7 +432,7 @@ monthlyBugsCreated: - groupB/project # Projects outside the group will be ignored ``` -## Complete example +## Complete insights configuration example ```yaml .projectsOnly: &projectsOnly |