Analytics dashboards

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.

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.

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.

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

Refer to the DashboardFilters type in the ee/app/validators/json_schemas/analytics_dashboard.json for a list of supported filters.

  1. Create a folder for your visualizations (for example visualizations/) in your dashboard directory and add configuration files for each visualization. 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.

  1. Add panels to your dashboard that reference your visualizations:

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

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

  3. Register the visualization by adding it 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.
note
Your data source must respect the filters so that all panels shows the same filtered data.

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