• How product analytics works
• Enable product analytics
  • Product analytics provider
  • Instance-level settings
  • Group-level settings
  • Project-level settings
• Onboard a GitLab project
  • On GitLab.com
  • On GitLab self-managed or GitLab Dedicated
• Instrument your application
• Product analytics dashboards
  • Filling missing data
• Funnel analysis
  • Example funnel definition
  • Query a funnel
• Raw data export
  • Export raw data with Cube queries
• View product analytics usage quota
• Best practices
• Troubleshooting
  • No events are collected
  • Access to product analytics is restricted

Product analytics

For more information about the vision and development of product analytics, see the group direction page. To leave feedback about product analytics bugs or functionality:

• Comment on issue 391970.
• Create an issue with the group::product analytics label.

How product analytics works

Product analytics uses the following tools:

• Snowplow - A developer-first engine for collecting behavioral data and passing it through to ClickHouse.
• ClickHouse - A database suited to store, query, and retrieve analytical data.
• Cube - A universal semantic layer that provides an API to run queries against the data stored in ClickHouse.

The following diagram illustrates the product analytics flow:

Enable product analytics

To track events in your project’s applications, you must enable and configure product analytics.

Product analytics provider

Your GitLab instance connects to a product analytics provider. A product analytics provider is the collection of services required to receive, process, store and query your analytics data.

Instance-level settings

Offering: Self-managed, GitLab Dedicated

Prerequisites:

• You must have administrator access for the instance.

To enable product analytics on your instance:

1. On the left sidebar, at the bottom, select Admin Area.
2. Select Settings > Analytics.
3. Expand Product analytics and enter the configuration values.
4. Select Save changes.

Group-level settings

Prerequisites:

• You must have the Owner role for the group.

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand the Permissions and group features section.
4. Check Use Experiment and Beta features checkbox.
5. Select Save changes.

Project-level settings

If you want to have a product analytics instance with a different configuration for your project, you can override the instance-level settings defined by the administrator on a per-project basis.

Prerequisites:

• You must have at least the Maintainer role for the project or group the project belongs to.
• The project must be in a group namespace.

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Analytics.
3. Expand Data sources and enter the configuration values.
4. Select Save changes.

Onboard a GitLab project

Prerequisites:

• You must have at least the Developer role for the project or group the project belongs to.

Onboarding a GitLab project means preparing it to receive events that are used for product analytics.

To onboard a project:

1. On the left sidebar, select Search or go to and find your project.
2. Select Analyze > Analytics dashboards.
3. Under Product analytics, select Set up.

Then continue with the setup depending on your environment.

On GitLab.com

On GitLab self-managed or GitLab Dedicated

• Select Set up product analytics. Project-level settings are used if defined, otherwise instance-level settings.

Your instance is being created, and the project onboarded.

Instrument your application

You can instrument code to collect data by using tracking SDKs.

Product analytics dashboards

Product analytics dashboards are a subset of dashboards under Analytics dashboards.

Specifically, product analytics dashboards and visualizations use the cube_analytics data type. The cube_analytics data type connects to the Cube instance defined when product analytics was enabled. All filters and queries are sent to the Cube instance, and the returned data is processed by the product analytics data source to be rendered by the appropriate visualizations.

Data table visualizations from cube_analytics have an additional configuration option for rendering links. This option is an array of objects, each with text and href properties to specify the dimensions to be used in links. If href contains multiple dimensions, values are joined into a single URL. View an example.

Filling missing data

When exporting data or viewing dashboards, if there is no data for a given day, the missing data is autofilled with 0.

The autofill approach has both benefits and limitations.

• Benefits:
  • The visualization’s day axis matches the selected date range, removing ambiguity about missing data.
  • Data exports have rows for the entire date range, making data analysis easier.
• Limitations:
  • The day granularity must be used. All other granularities are not supported.
  • Only date ranges defined by the inDateRange filter are filled.
    • The date selector in the UI already uses this filter.
  • The filling of data ignores the query-defined limit. If you set a limit of 10 data points over 20 days, it returns 20 data points, with the missing data filled by 0. Issue 417231 proposes a solution to this limitation.

Funnel analysis

Use funnel analysis to understand the flow of users through your application, and where users drop out of a predefined flow (for example, a checkout process or ticket purchase).

Each product can also define an unlimited number of funnels. Like dashboards, funnels are defined with the GitLab YAML schema and stored in the .gitlab/analytics/funnels/ directory of a project repository.

Funnel definitions must include the keys name and seconds_to_convert, and an array of steps.

Each step must include the keys name, target, and action.

Example funnel definition

The following example defines a funnel that tracks users who completed a purchase within one hour by going through three target pages:

name: completed_purchase
seconds_to_convert: 3600
steps:
  - name: view_page_1
    target: '/page1.html'
    action: 'pageview'
  - name: view_page_2
    target: '/page2.html'
    action: 'pageview'
  - name: view_page_3
    target: '/page3.html'
    action: 'pageview'

Query a funnel

You can query the funnel data with the REST API. To do this, you can use the example query body below, where you need to replace FUNNEL_NAME with your funnel’s name.

{
  "query": {
      "measures": [
        "FUNNEL_NAME.count"
      ],
      "order": {
        "completed_purchase.count": "desc"
      },
      "filters": [
        {
          "member": "FUNNEL_NAME.date",
          "operator": "beforeDate",
          "values": [
            "2023-02-01"
          ]
        }
      ],
      "dimensions": [
        "FUNNEL_NAME.step"
      ]
    }
}

Raw data export

Exporting the raw event data from the underlying storage engine can help you debug and create datasets for data analysis.

Because Cube acts as an abstraction layer between the raw data and the API, the exported raw data has some caveats:

• Data is grouped by the selected dimensions. Therefore, the exported data might be incomplete, unless including both utcTime and userAnonymousId.
• Data is by default limited to 10,000 rows, but you can increase the limit to maximum 50,000 rows. If your dataset has more than 50,000 rows, you must paginate through the results by using the limit and offset parameters.
• Data is always returned in JSON format. If you need it in a different format, you need to convert the JSON to the required format using a scripting language of your choice.

Issue 391683 tracks efforts to implement a more scalable export solution.

Export raw data with Cube queries

You can query the raw data with the REST API, and convert the JSON output to any required format.

To export the raw data for a specific dimension, pass a list of dimensions to the dimensions key. For example, the following query outputs the raw data for the attributes listed:

POST /api/v4/projects/PROJECT_ID/product_analytics/request/load?queryType=multi

{
    "query":{
  "dimensions": [
    "TrackedEvents.docEncoding",
    "TrackedEvents.docHost",
    "TrackedEvents.docPath",
    "TrackedEvents.docSearch",
    "TrackedEvents.eventType",
    "TrackedEvents.localTzOffset",
    "TrackedEvents.pageTitle",
    "TrackedEvents.src",
    "TrackedEvents.utcTime",
    "TrackedEvents.vpSize"
  ],
  "order": {
    "TrackedEvents.apiKey": "asc"
  }
    }
}

If the request is successful, the returned JSON includes an array of rows of results.

View product analytics usage quota

Product analytics usage quota is calculated from the number of events received from instrumented applications.

To view product analytics usage quota:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > Usage quota.
3. Select the Product analytics tab.

The tab displays the monthly totals for the group and a breakdown of usage per project. The current month displays events counted to date.

The usage quota excludes projects that are not onboarded with product analytics.

Best practices

• Define key metrics and goals from the start. Decide what questions you want to answer so you know how to use collected data.
• Use event data from all stages of the user journey. This data provides a comprehensive view of the user experience.
• Build dashboards aligned with team needs. Different teams need different data insights.
• Review dashboards regularly. This way, you can verify customer outcomes, identify trends in data, and update visualizations.
• Export raw data periodically. Dashboards provide only an overview of a subset of data, so you should export the data for a deeper analysis.

Troubleshooting

No events are collected

Check your instrumentation details, and make sure product analytics is enabled and set up correctly.

Access to product analytics is restricted

Check that you are connected to a product analytics provider.