Event data

Data tracking for product usage at event level

For more information about changes to product usage data collection, read the blog post More granular product usage insights for GitLab Self-Managed and Dedicated.

Event data

Event data tracks interactions (or actions) within the GitLab platform. These interactions or actions could be user initiated such as initiating CI/CD pipelines, merging a merge request, triggering a webhook, or creating an issue. Actions can also result from background system processing like scheduled pipeline succeeding. The focus of event data collection is on the users’ actions and the metadata associated with those actions.

User IDs are pseudonymized to protect privacy, and GitLab does not undertake any processes to re-identify or associate the metrics with individual users. Event data does not include source code or other customer-created content stored within GitLab.

For more information, see also:

• Metrics dictionary for a list of events and metrics
• Customer product usage information

Benefits of event data

Event-level data enhances several benefits of Service Ping by offering more granular insights without identifying users.

• Proactive support: Granular data allows our Customer Success Managers (CSMs) and support teams to access more detailed information, enabling them to drill down and create custom metrics tailored to your organization’s unique needs, rather than relying on more generic, aggregated metrics.
• Targeted guidance: Event-level data provides a deeper understanding of how features are used, helping us uncover opportunities for optimization and improvement. The depth of data allows us to offer more precise, actionable recommendations to help you maximize the value of GitLab and enhance your workflows.
• Anonymized benchmarking reports: Granular event data enables more accurate and relevant performance comparisons with similar organizations by focusing on detailed usage patterns, rather than just high-level aggregated data.

Enable or disable event-level data collection

To enable or disable event-level data collection:

1. Sign in as a user with administrator access.
2. In the upper-right corner, select Admin.
3. Select Settings > Metrics and Profiling.
4. Expand Event tracking.
5. To enable the setting, select the checkbox Enable event tracking. To disable the setting, clear the checkbox.
6. Select Save changes.

Programmatically configure event-level data collection

You can configure event-level data collection programmatically using either:

• Initial defaults: Apply only during first-time installation
• Environment variable override: Apply at runtime and take precedence over database settings

Initial defaults (installation only)

These settings only apply during the initial installation of GitLab. Changing these settings after installation has no effect.

gitlab_rails['initial_gitlab_product_usage_data'] = false

sudo gitlab-ctl reconfigure

global:
  appConfig:
    initialDefaults:
      gitlabProductUsageData: false

helm install gitlab gitlab/gitlab \
  --set global.appConfig.initialDefaults.gitlabProductUsageData=false

Environment variable override (runtime)

The GITLAB_PRODUCT_USAGE_DATA_ENABLED environment variable allows you to control event-level data collection at runtime. When set, this environment variable:

• Takes precedence over the database setting
• Cannot be changed through the Admin UI (the toggle is disabled)
• Applies immediately without requiring a database migration

This is useful for:

• Air-gapped environments requiring automated configuration
• Deployments that need consistent settings across upgrades
• Automated deployment workflows where UI access is not practical

Valid values are true or false.

gitlab_rails['env']['GITLAB_PRODUCT_USAGE_DATA_ENABLED'] = 'false'

sudo gitlab-ctl reconfigure

gitlab:
  sidekiq:
    extraEnv:
      GITLAB_PRODUCT_USAGE_DATA_ENABLED: 'false'
  webservice:
    extraEnv:
      GITLAB_PRODUCT_USAGE_DATA_ENABLED: 'false'

helm upgrade gitlab gitlab/gitlab \
  --set gitlab.sidekiq.extraEnv.GITLAB_PRODUCT_USAGE_DATA_ENABLED='false' \
  --set gitlab.webservice.extraEnv.GITLAB_PRODUCT_USAGE_DATA_ENABLED='false'

docker run --env GITLAB_PRODUCT_USAGE_DATA_ENABLED=false gitlab/gitlab-ee:latest

services:
  gitlab:
    image: gitlab/gitlab-ee:latest
    environment:
      GITLAB_PRODUCT_USAGE_DATA_ENABLED: 'false'

export GITLAB_PRODUCT_USAGE_DATA_ENABLED=false

Check the current setting source

When the environment variable override is active, the Admin UI displays a warning banner indicating that the setting is controlled by an environment variable and cannot be changed through the UI.

You can also check the setting source through the API:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/application/settings" | jq '.gitlab_product_usage_data_enabled, .gitlab_product_usage_data_source'

The gitlab_product_usage_data_source field returns either:

• environment: The setting is controlled by the GITLAB_PRODUCT_USAGE_DATA_ENABLED environment variable
• database: The setting is controlled by the database (can be changed via Admin UI)

Event delivery timing

Events are transmitted to GitLab almost immediately after they occur. The system collects events in small batches, sending data once 10 events have been gathered. This approach provides near real-time delivery while maintaining efficient network usage.

Payload size and compression

Each event is approximately 10 kB in JSON format. Batches of 10 events result in an uncompressed payload size of about 100 kB. Before transmission, the payload is compressed to minimize data transfer size and optimize performance.

Event data logs

Event-level tracking data is logged in the product_usage_data.log file. This log contains JSON-formatted entries of tracked product usage events, including payload information and context data. Each line represents a separate tracking event and all the data that was sent.

The log file is located at:

• /var/log/gitlab/gitlab-rails/product_usage_data.log on Linux package installations
• /home/git/gitlab/log/product_usage_data.log on self-compiled installations

While these logs provide thorough visibility into data transmission, they’re designed specifically for inspection by security teams rather than feature usage analysis. For more detailed information about logging system, see the Log system documentation.