Analytics dashboards

Analytics dashboards provide a configuration-based dashboard structure, which is used to render and modify dashboard configurations created by GitLab or users.

Customizable dashboard framework

Analytics dashboards utilize a set of standardized UI components that ensure a consistent user experience. These components are modular and can be integrated into other dashboard interfaces where basic visualization capabilities are needed, without advanced features like data fetching, filtering, or editing.

Note that we are currently migrating these components to GitLab UI. During this transition period, components may be located in either the legacy system or the new GitLab UI framework.

• vue_shared/components/customizable_dashboard
• GlDashboardPanel

Overview

Analytics dashboard can be broken down into the following logical components:

• Dashboard: The container that organizes and displays all visualizations
• Panels: Individual sections that host visualizations
• Visualizations: Data display templates (charts, tables, etc.)
• Data sources: Connections to the underlying data

Dashboard

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

Dashboard filters

Dashboards support the following filters:

• Date range: Date selector to filter data by date.
• Anonymous users: Toggle to include or exclude anonymous users from the dataset.
• Project: Dropdown list to filter data by project.
• Filtered search: Filter bar to filter data by selected attributes.

Dashboard status

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:

• experiment
• beta

Panel

Panels 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.

Visualization

A visualization transforms your data into a graphical format like a chart or table. You can use the following standard visualization types:

• LineChart
• ColumnChart
• DataTable
• SingleStats

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.

Data source

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.

Note that each panel fetches data from the data source separately and independently from other panels.

Create a built-in dashboard

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:

1. Create a folder for the new dashboard under ee/lib/gitlab/analytics, for example:

   ee/lib/gitlab/analytics/cool_dashboard

2. 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: []

3. 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.

4. Optional. Set the appropriate status of the dashboard if it is not production ready:

   # cool_dashboard/dashboard.yaml
   ---
   title: My dashboard
   status: experiment

5. 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.

6. 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"
         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"
         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.

7. Register the dashboard by adding it to builtin_dashboards in ee/app/models/product_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.

8. Optional. Register visualization templates by adding them to get_path_for_visualization in ee/app/models/product_analytics/visualization.rb.

For a complete example, refer to the AI Impact dashboard config.

Adding a new data source

To add a new data source:

1. Create a new JavaScript module that exports a 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 example
2. Add your module to the list exports in data_sources/index.js.
3. Add your data source to the schema’s list of Data types in analytics_visualizations.json.

Adding a new visualization render type

To add a new visualization render type:

1. Create a new Vue component that accepts data and options properties. See line_chart.vue as an example.
2. Add your component to the list of conditional components imports in analytics_dashboard_panel.vue.
3. Add your component to the schema’s list of AnalyticsVisualization enum type in analytics_visualization.json.

Migrating existing components to visualizations

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.

Introducing visualizations behind a feature flag

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