Help us learn about your current experience with the documentation. Take the survey.

洞察

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

洞察是交互式条形图，显示每月的项目数量（例如，创建的 bug 数量）。

为您的项目和组配置洞察并创建自定义报告，以探索以下数据：

指定期间内创建和关闭的问题。
合并请求被合并的平均时间。
问题分类质量。

查看洞察

前提条件：

对于项目洞察，您必须有权访问项目，并有权查看其合并请求和问题的信息。
对于组洞察，您必须有权查看该组。

要查看项目或组的洞察：

在左侧边栏，选择 搜索或跳转至 并找到您的项目或组。
选择 分析 > 洞察。
要查看报告，从 选择报告 下拉列表中选择您要查看的报告。要查看注释，请将鼠标悬停在图表中的每个条形上。
可选。过滤结果：
- 仅显示 90 天范围内的部分数据，选择暂停图标（）并沿水平轴滑动它们。
- 要从图表中排除某个维度，请从图表下方的图例中选择该维度的名称。

钻取图表数据

您可以钻取所有 query.data_source 为 issuables 的图表数据。

要查看特定优先级或严重性在特定月份数据的钻取报告：

在图表上，选择您要钻取的条形堆栈。

创建报告深度链接

您可以使用深度链接 URL 将用户直接引导到洞察中的特定报告。

要创建深度链接，请将报告键附加到洞察报告 URL 的末尾。例如，键为 bugsCharts 的 GitLab 报告的深度链接 URL 为 https://gitlab.com/gitlab-org/gitlab/insights/#/bugsCharts。

配置

默认文件

GitLab 从默认配置文件读取洞察数据。

项目洞察使用项目中的 .gitlab/insights.yml 文件进行配置。如果项目没有配置文件，则使用组配置。

.gitlab/insights.yml 文件是一个 YAML 文件，您可以在其中定义：

报告中图表的结构和顺序。
项目或组报告中显示的图表样式。

在 .gitlab/insights.yml 文件中：

配置参数定义图表行为。
每个报告都有唯一的键和要获取并显示的图表集合。
每个图表定义都是由键值对组成的哈希。

示例

以下示例显示了一个定义，用于显示包含一个图表的报告：

bugsCharts:
  title: "Bug 图表"
  charts:
    - title: "每月创建的 Bug"
      description: "每月创建的开放 Bug"
      type: bar
      query:
        data_source: issuables
        params:
          issuable_type: issue
          issuable_state: opened
          filter_labels:
            - bug
          group_by: month
          period_limit: 24

以下示例显示了显示三个图表的完整 .gitlab/insights.yml 配置：

.projectsOnly: &projectsOnly
  projects:
    only:
      - 3
      - groupA/projectA
      - groupA/subgroupB/projectC

bugsCharts:
  title: "Bug 图表"
  charts:
    - title: "每月创建的 Bug"
      description: "每月创建的开放 Bug"
      type: bar
      <<: *projectsOnly
      query:
        data_source: issuables
        params:
          issuable_type: issue
          issuable_state: opened
          filter_labels:
            - bug
          group_by: month
          period_limit: 24

    - title: "按严重性分类的每周 Bug"
      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: "按团队分类的每月 Bug"
      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

参数

下表列出了图表参数：

关键字	描述
`title`	图表的标题。此标题显示在洞察页面上。
`description`	单个图表的描述。此描述显示在相关图表上方。
`type`	图表类型：`bar`、`line` 或 `stacked-bar`。
`query`	定义图表的数据源和过滤条件的哈希。

`title`

使用 title 更新图表标题。标题显示在洞察报告中。

示例：

monthlyBugsCreated:
  title: "每月创建的 Bug"

`description`

使用 description 添加图表的描述。描述显示在图表上方、标题下方。

示例：

monthlyBugsCreated:
  title: "每月创建的 Bug"
  description: "每月创建的开放 Bug"

`type`

使用 type 定义图表类型。

支持的值：

名称	示例：
`bar`
`bar`（带 `group_by` 的时间序列）
`line`
`stacked-bar`

dora 数据源支持 bar 和 line 图表类型。

示例：

monthlyBugsCreated:
  title: "每月创建的 Bug"
  type: bar

`query`

使用 query 定义图表的数据源和过滤条件。

示例：

monthlyBugsCreated:
  title: "每月创建的 Bug"
  description: "每月创建的开放 Bug"
  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

仍然支持不带 data_source 参数的旧格式：

monthlyBugsCreated:
  title: "每月创建的 Bug"
  description: "每月创建的开放 Bug"
  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`

使用 data_source 定义提供数据的源。

支持的值：

issuables: 提供合并请求或问题数据。
dora: 提供 DORA 指标。

`issuable` 查询参数

`query.params.issuable_type`

使用 query.params.issuable_type 定义要创建图表的可追踪项类型。

支持的值：

issue: 图表显示问题的数据。
merge_request: 图表显示合并请求的数据。

`query.params.issuable_state`

使用 query.params.issuable_state 根据所查询可追踪项的当前状态进行过滤。

默认应用 opened 状态过滤器。

支持的值：

opened: 开放的问题或合并请求。
closed: 已关闭的问题或合并请求。
locked: 讨论被锁定的问题或合并请求。
merged: 已合并的合并请求。
all: 所有状态的问题或合并请求。

`query.params.filter_labels`

使用 query.params.filter_labels 根据应用于所查询可追踪项的标签进行过滤。

默认不应用标签过滤器。所有定义的标签都必须应用于可追踪项才能被选中。

示例：

monthlyBugsCreated:
  title: "每月创建的回归问题"
  type: bar
  query:
    data_source: issuables
    params:
      issuable_type: issue
      issuable_state: opened
      filter_labels:
        - bug
        - regression

`query.params.collection_labels`

使用 query.params.collection_labels 根据配置的标签对可追踪项进行分组。默认不应用分组。

示例：

weeklyBugsBySeverity:
  title: "按严重性分类的每周 Bug"
  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`

使用 query.group_by 定义图表的 X 轴。

支持的值：

day: 按天分组数据。
week: 按周分组数据。
month: 按月分组数据。

`query.period_limit`

使用 query.period_limit 定义查询可追踪项的时间范围（使用 query.period_field）。

单位与 query.group_by 中定义的值相关。例如，如果您定义了 query.group_by: 'day'，并且 query.period_limit: 365，则图表显示过去 365 天的数据。

默认根据您定义的 query.group_by 应用默认值。

`query.group_by`	默认值
`day`	30
`week`	4
`month`	12

`query.period_field`

使用 query.period_field 定义用于对可追踪项进行分组的时间戳字段。

支持的值：

created_at（默认）：使用 created_at 字段分组数据。
closed_at：使用 closed_at 字段分组数据（仅适用于问题）。
merged_at：使用 merged_at 字段分组数据（仅适用于合并请求）。

period_field 会自动设置为：

如果 query.issuable_state 为 closed，则设置为 closed_at
如果 query.issuable_state 为 merged，则设置为 merged_at
否则为 created_at

直到此问题解决，您可能会看到 created_at 替代 merged_at。使用的是 created_at。

`DORA` 查询参数

使用 dora 数据源进行 DORA 特定查询，以创建 DORA 图表定义。

示例：

dora:
  title: "DORA 图表"
  charts:
    - title: "DORA 部署频率"
      type: bar # 或 line
      query:
        data_source: dora
        params:
          metric: deployment_frequency
          group_by: day
          period_limit: 10
      projects:
        only:
          - 38
    - title: "DORA 变更前置时间"
      description: "DORA 变更前置时间"
      type: bar
      query:
        data_source: dora
        params:
          metric: lead_time_for_changes
          group_by: day
          environment_tiers:
            - staging
          period_limit: 30

`query.metric`

使用 query.metric 定义要查询的 DORA 指标。

支持的值：

deployment_frequency（默认）
lead_time_for_changes
time_to_restore_service
change_failure_rate

`query.group_by`

使用 query.group_by 定义图表的 X 轴。

支持的值：

day（默认）：按天分组数据。
month: 按月分组数据。

`query.period_limit`

使用 query.period_limit 定义查询过去指标的时间范围（默认：15）。最大周期为 180 天或 6 个月。

`query.environment_tiers`

使用 query.environment_tiers 定义要包含计算的环境数组。

支持的值：

production（默认）
staging
testing
development
other

`projects`

使用 projects 限制查询可追踪项的来源：

如果 .gitlab/insights.yml 用于组的洞察，使用 projects 定义从中查询可追踪项的项目。默认使用组下的所有项目。
如果 .gitlab/insights.yml 用于项目的洞察，指定其他项目不会产生结果。默认使用该项目。

`projects.only`

使用 projects.only 指定从中查询可追踪项的项目。

当满足以下条件时，此参数中列出的项目将被忽略：

项目不存在。
当前用户没有足够的读取权限。
项目在组外。

示例：

monthlyBugsCreated:
  title: "每月创建的 Bug"
  description: "每月创建的开放 Bug"
  type: bar
  query:
    data_source: issuables
    params:
      issuable_type: issue
      issuable_state: opened
      filter_labels:
        - bug
  projects:
    only:
      - 3                         # 您可以使用项目 ID
      - groupA/projectA           # 或完整的项目路径
      - groupA/subgroupB/projectC # 可以包含子组中的项目
      - groupB/project            # 组外的项目将被忽略

配置洞察

您可以为项目和组配置洞察。在项目中创建 .gitlab/insights.yml 文件后，也可以将其用于该项目的组。

自定义的 .gitlab/insights.yml 文件会覆盖默认配置。要保留原始配置，请将默认配置文件的内容作为基础进行复制。

为项目配置

前提条件：

您必须至少拥有项目的 Developer 角色。

要配置项目洞察，创建一个 .gitlab/insights.yml 文件，方式如下：

在本地，在项目根目录中创建，然后推送您的更改。
从 UI 创建：
1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。
2. 在文件列表上方，选择您要提交到的分支，选择加号图标，然后选择 新建文件。
3. 对于 文件名，输入 .gitlab/insights.yml。
4. 在文件编辑器中，输入配置。请参阅配置示例。
5. 选择 提交更改。

为组配置

前提条件：

您的组中必须有一个包含 .gitlab/insights.yml 文件的项目。

要配置组洞察：

在左侧边栏，选择 搜索或跳转至 并找到您的组。
选择 设置 > 分析。
在洞察部分，选择一个包含 .gitlab/insights.yml 配置文件的项目。
选择 保存更改。

洞察

查看洞察

钻取图表数据

创建报告深度链接

配置

默认文件

示例

参数

title

description

type

query

query.data_source

issuable 查询参数

query.params.issuable_type

query.params.issuable_state

query.params.filter_labels

query.params.collection_labels

query.group_by

query.period_limit

query.period_field

DORA 查询参数

query.metric

query.group_by

query.period_limit

query.environment_tiers

projects

projects.only

配置洞察

为项目配置

为组配置

`title`

`description`

`type`

`query`

`query.data_source`

`issuable` 查询参数

`query.params.issuable_type`

`query.params.issuable_state`

`query.params.filter_labels`

`query.params.collection_labels`

`query.group_by`

`query.period_limit`

`query.period_field`

`DORA` 查询参数

`query.metric`

`query.group_by`

`query.period_limit`

`query.environment_tiers`

`projects`

`projects.only`