doc/development/fe_guide/analytics_dashboards.md
{{< history >}}
{{< /history >}}
Analytics dashboards provide a configuration-based dashboard structure, which is used to render and modify dashboard configurations created by GitLab or users.
[!note] Analytics dashboards is intended for Premium and Ultimate subscriptions.
Analytics dashboard can be broken down into the following logical components:
A dashboard combines a collection of data sources, panels and visualizations into a single page to visually represent data.
Each panel in the dashboard queries the relevant data source and displays the resulting data as the specified visualization. Visualizations serve as templates for how to display data and can be reused across different panels.
A typical dashboard structure looks like this:
dashboard
├── panelA
│ └── visualizationX
│ └── datasource1
├── panelB
│ └── visualizationY
│ └── datasource2
├── panelC
│ └── visualizationY
│ └── datasource1
Dashboards support the following filters:
Dashboards with a status badge indicate their development stage and functionality. Dashboards without a status badge are fully developed and production-ready.
The supported options are:
experimentbetaPanels form the foundation of a dashboard and act as containers for your visualizations. Each panel is built using the GitLab standardized UI component called GlDashboardPanel.
A visualization transforms your data into a graphical format like a chart or table. You can use the following standard visualization types:
For a list of all supported visualization types, see AnalyticsVisualization.type enum in analytics_visualization.
You're not limited to these options though - you can create new visualization types as needed.
A data source is a connection to a database, an endpoint or a collection of data which can be used by your dashboard to query, retrieve, filter, and visualize results.
While there's a core set of supported data sources (see Data.type enum in analytics_visualizations), you can add new ones to meet your needs.
To support all visualization types, ensure your data source returns data as a single aggregated value and a time series with a value for each point in time.
Note that each panel fetches data from the data source separately and independently from other panels.
GitLab provides predefined dashboards that are labeled By GitLab. Users cannot edit them, but they can clone or use them as the basis for creating similar custom dashboards.
To create a built-in analytics dashboard:
Create a folder for the new dashboard under ee/lib/gitlab/analytics, for example:
ee/lib/gitlab/analytics/cool_dashboard
Create a dashboard configuration file (for example dashboard.yaml) in the new folder. The configuration must conform to the JSON schema defined in ee/app/validators/json_schemas/analytics_dashboard.json. Example:
# cool_dashboard/dashboard.yaml
---
title: My dashboard
description: My cool dashboard
panels: []
Optional. Enable dashboard filters by setting the filter's enabled option to true in the .yaml configuration file :
# cool_dashboard/dashboard.yaml
---
title: My dashboard
filters:
excludeAnonymousUsers:
enabled: true
dateRange:
enabled: true
projects:
enabled: true
filteredSearch:
enabled: true
# Use `options` to define an array of tokens to override the default ones
options:
- token: assignee
unique: false
- token: label
maxSuggestions: 10
Refer to the DashboardFilters type in the ee/app/validators/json_schemas/analytics_dashboard.json for a list of supported filters.
Optional. Set the appropriate status of the dashboard if it is not production ready:
# cool_dashboard/dashboard.yaml
---
title: My dashboard
status: experiment
Optional. Create visualization templates by creating a folder for your templates (for example visualizations/) in your dashboard directory and
add configuration files for each template.
Visualization templates might be used when a visualization will be used by multiple dashboards. Use a template to prevent duplicating the same YAML block multiple times. For built-in dashboards, the dashboard will automatically update when the visualization template is changed. For user-defined dashboards, the visualization template is copied rather than referenced. Visualization templates copied to dashboards are not updated when the visualization template is updated.
Each file must conform to the JSON schema defined in ee/app/validators/json_schemas/analytics_visualization.json.
Example:
# cool_dashboard/visualizations/cool_viz.yaml
---
version: 1
type: LineChart # The render type of the visualization.
data:
type: my_datasource # The name of the datasource
query: {}
options: {}
Both query and options objects will be passed to the data source and used to build the proper query.
Refer to Data source for a list of supported data sources, and Visualization for a list of supported visualization render types.
To add panels to your dashboard that reference your visualizations, use either:
Recommended. Use an inline visualization within the dashboard configuration file:
# cool_dashboard/dashboard.yaml
---
title: My dashboard
description: My cool dashboard
panels:
- title: "My cool panel"
tooltip:
description: "This is a cool panel. %{linkStart}Learn more%{linkEnd}."
descriptionLink: "https://gitlab.com"
visualization:
version: 1
slug: 'cool_viz' # Recommended to define a slug when a visualization is inline
type: LineChart # The render type of the visualization.
data:
type: my_datasource # The name of the datasource
query: {}
options: {}
gridAttributes:
yPos: 0
xPos: 0
width: 3
height: 1
Both query and options objects will be passed to the data source and used to build the proper query.
Refer to Data source for a list of supported data sources, and Visualization for a list of supported visualization render types.
Use a visualization template:
# cool_dashboard/dashboard.yaml
---
title: My dashboard
description: My cool dashboard
panels:
- title: "My cool panel"
tooltip:
description: "This is a cool panel. %{linkStart}Learn more%{linkEnd}."
descriptionLink: "https://gitlab.com"
visualization: cool_viz # Must match the visualization config filename
gridAttributes:
yPos: 0
xPos: 0
width: 3
height: 1
The gridAttributes position the panel within a 12x12 dashboard grid, powered by gridstack.
tooltip adds a help icon next to the panel title that displays contextual help on hover, using description text and an optional descriptionLink to embed a link between the %{linkStart} and %{linkEnd} placeholders. You can also define a tooltip at the visualization level in visualization.options or dynamically using the setVisualizationOverrides callback function from a data source. Note that panel-level tooltips take precedence over visualization-level tooltips.
Register the dashboard by adding it to builtin_dashboards in ee/app/models/analytics/dashboard.rb.
Here you can make your dashboard available at project-level or group-level (or both), restrict access based on feature flags, license or user role etc.
Optional. Register visualization templates by adding them to get_path_for_visualization in ee/app/models/analytics/visualization.rb.
For a complete example, refer to the GitLab Duo and SDLC trends dashboard config.
To add a new data source:
fetch method. See analytics_dashboards/data_sources/index.js for the full documentation of the fetch API. You can also take a look atcube_analytics.js as an exampledata_sources/index.js.Data types in analytics_visualizations.json.[!note] Your data source must respect the filters so that all panels shows the same filtered data.
To add a new visualization render type:
data and options properties.
See line_chart.vue as an example.line_chart.stories.js as an example.analytics_dashboard_panel.vue.AnalyticsVisualization enum type in analytics_visualization.json.You can migrate existing components to dashboard visualizations. To do this,
wrap your existing component in a new visualization that provides the component with the
required context and data. See dora_performers_score.vue as an example.
As an upgrade path, your component may fetch its own data internally.
But you should ensure to plan how to migrate your visualization to use the shared analytics data sources method.
See value_stream.js as an example.
While developing new visualizations we can use feature flags to mitigate risks of disruptions or incorrect data for users.
The from_data method builds the panel objects for a dashboard. Using the filter_map method, we can add a condition to skip rendering panels that include the visualization we are developing.
For example, here we have added the enable_usage_overview_visualization feature flag and can check it's current state to determine whether panels using the usage_overview visualization should be rendered:
panel_yaml.filter_map do |panel|
# Skip processing the usage_overview panel if the feature flag is disabled
next if panel['visualization'] == 'usage_overview' && Feature.disabled?(:enable_usage_overview_visualization)
new(
title: panel['title'],
project: project,
grid_attributes: panel['gridAttributes'],
query_overrides: panel['queryOverrides'],
visualization: panel['visualization']
)
end