diff options
Diffstat (limited to 'doc/user/analytics/analytics_dashboards.md')
| -rw-r--r-- | doc/user/analytics/analytics_dashboards.md | 185 |
1 files changed, 109 insertions, 76 deletions
diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index e29e02c867f..9d2c91b6bc8 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.md @@ -9,21 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 15.9 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. On GitLab.com, this feature is not available. This feature is not ready for production use. -## Dashboards +Analytics dashboards help you visualize the collected data. +You can use built-in dashboards or create your own with custom visualizations. -Each project can have an unlimited number of dashboards, only limited by the instances [repository size limits](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). -These dashboards are defined using the GitLab YAML schema, and stored in the `.gitlab/analytics/dashboards/` directory of a project repository. -The dashboard file name and containing directory should be the same, for example `my_dashboard/my_dashboard.yaml`. For more information see [defining a dashboard](#define-a-dashboard). -Each dashboard can reference one or more [visualizations](#define-a-chart-visualization), which are shared across dashboards. - -Project maintainers can enforce approval rules on dashboard changes using features such as [code owners](../project/codeowners/index.md) and [approval rules](../project/merge_requests/approvals/rules.md). -Your dashboard files are versioned in source control with the rest of a project's code. - -### Data sources +## Data sources A data source is a connection to a database or collection of data which can be used by your dashboard filters and visualizations to query and retrieve results. @@ -32,15 +25,96 @@ The following data sources are configured for analytics dashboards: - [Product analytics](../product_analytics/index.md) -### View project dashboards +## Built-in dashboards + +To help you get started with analytics, GitLab provides two built-in dashboards with predefined visualizations: + +- **Audience**, which displays metrics related to traffic, such as number of users and sessions. +- **Behavior**, which displays metrics related to user activity, such as number of page views and events. + +These dashboards are labeled **By GitLab**, and you cannot edit them. +Instead, you can create a custom dashboard with a similar style. + +## Custom dashboards -To view a list of dashboards for a project: +With custom dashboards, you can design and create visualizations for the metrics that are most relevant to your use case. +You can create custom dashboards with the dashboard designer. + +- Each project can have an unlimited number of dashboards. +The only limitation might be the [repository size limit](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). +- Each dashboard can reference one or more [visualizations](#define-a-chart-visualization). +- Visualizations are shared across dashboards. + +Project maintainers can enforce approval rules on dashboard changes with features such as [code owners](../project/codeowners/index.md) and [approval rules](../project/merge_requests/approvals/rules.md). +Your dashboard files are versioned in source control with the rest of a project's code. + +## Dashboard designer + +> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +NOTE: +This feature does not work in conjunction with the `product_analytics_snowplow_support` feature flag. + +You can use the dashboard designer to: + +- Create custom dashboards. +- Rename custom dashboards. +- Add visualizations to new and existing custom dashboards. +- Resize or move panels in custom dashboards. + +## View project dashboards + +To view a list of dashboards (both built-in and custom) for a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Analyze > Dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. -### Define a dashboard +## Change the location of dashboards + +You can change the location of your project or group dashboards. + +### Group dashboards + +NOTE: +This feature will be connected to group-level dashboards as part of [issue #411572](https://gitlab.com/gitlab-org/gitlab/-/issues/411572). + +To change the location of a group's dashboards: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to store your dashboard files in. + The project must belong to the group for which you create the dashboards. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In the **Analytics Dashboards** section, select your dashboard files project. +1. Select **Save changes**. + +### Project dashboards + +Dashboards are usually defined in the project where the analytics data is being retrieved from. +However, you can also have a separate project for dashboards. +This is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects. + +NOTE: +You can share dashboards only between projects that are located in the same group. + +To change the location of project dashboards: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project, + or select **Create new...** (**{plus}**) and **New project/repository** + to create the project to store your dashboard files. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and find the analytics project. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In the **Analytics Dashboards** section, select your dashboard files project. +1. Select **Save changes**. + +## Define a dashboard To define a dashboard: @@ -67,7 +141,7 @@ and one visualization (line chart) that applies to all dashboards, the file stru │ └── example_line_chart.yaml ``` -### Define a chart visualization +## Define a chart visualization You can define different charts, and add visualization options to some of them: @@ -91,65 +165,7 @@ create a `line_chart.yaml` file with the following required fields: - data - options -### Change the location of project dashboards - -Dashboards are usually defined in the project where analytics data is being retrieved. -However, you can also have a separate project for dashboards. -This is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects. - -NOTE: -You can share dashboards only between projects that are located in the same group. - -To change the location of project dashboards: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project, - or select **Create new...** (**{plus}**) and **New project/repository** - to create the project to store your dashboard files. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and find the project you want to use the dashboards for. -1. Select **Settings > General**. -1. Expand **Analytics**. -1. In the **Analytics Dashboards** section, select the project that contains the dashboard files. -1. Select **Save changes**. - -### Change the location of group dashboards - -NOTE: -This feature will be connected to group-level dashboards in [issue 411572](https://gitlab.com/gitlab-org/gitlab/-/issues/411572). - -If you want to use dashboards for a group, you must store the dashboard files in a project that belongs to that group. -You can change the source project of a group's dashboards at any time. - -To change the location of a group's dashboards: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Settings > General**. -1. Expand **Analytics**. -1. In the **Analytics Dashboards** section, select the project that contains the dashboard files. -1. Select **Save changes**. - -## Dashboards designer - -> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - -NOTE: -This feature does not work in conjunction with the `product_analytics_snowplow_support` feature flag. - -You can use the dashboards designer to: - -- Create custom dashboards -- Rename custom dashboards -- Add visualizations to new and existing custom dashboards -- Resize or move panels within custom dashboards - -You cannot edit the built-in dashboards labeled as `By GitLab`. -To edit these dashboards you should create a new custom dashboard which uses the same visualizations. - -### Create a custom dashboard +## Create a custom dashboard To create a custom dashboard: @@ -161,9 +177,9 @@ To create a custom dashboard: 1. Optional. Drag or resize the selected panel how you prefer. 1. Select **Save**. -### Edit a custom dashboard +## Edit a custom dashboard -You can edit your custom dashboard's title and add or resize visualizations within the dashboard designer. +You can edit your custom dashboard's title and add or resize visualizations in the dashboard designer. To edit an existing custom dashboard: @@ -175,3 +191,20 @@ To edit an existing custom dashboard: 1. Optional. From the **Add visualizations** list on the right, select other visualizations to add to the dashboard. 1. Optional. In the dashboard, select a panel and drag or resize it how you prefer. 1. Select **Save**. + +## Troubleshooting + +### `Something went wrong while loading the dashboard.` + +If the dashboard displays a global error message that data could not be loaded, first try reloading the page. If the error persists: + +- Check that your configurations match the [JSON schema](#define-a-dashboard) defined in `ee/app/validators/json_schemas/analytics_dashboard.json`. +- For product analytics, check your [admin and project settings](../product_analytics/index.md#project-level-settings), and make sure they are set up correctly. + +### Dashboard panel error + +If a dashboard panel displays an error message: + +- Check your [Cube query](../product_analytics/index.md#product-analytics-dashboards) and [visualization](../analytics/analytics_dashboards.md#define-a-chart-visualization) +configurations, and make sure they are set up correctly. +- For [product analytics](../product_analytics/index.md), also check that your visualization's Cube query is valid. |