Local setup and debugging

Internal events are using a tool called Snowplow under the hood. To develop and test internal events, there are several tools related to Snowplow to test frontend and backend events:

Testing ToolFrontend TrackingBackend TrackingLocal Development EnvironmentProduction EnvironmentProduction Environment
Snowplow Analytics Debugger Chrome ExtensionYesNoYesYesYes
Snowplow MicroYesYesYesNoNo

For local development you will have to either setup a local event collector or configure a remote event collector. We recommend the local setup when actively developing new events.

Setup local event collector

By default, self-managed instances do not collect event data via Snowplow. We can use Snowplow Micro, a Docker based Snowplow collector, to test events locally:

  1. Ensure Docker is installed and working.

  2. Enable Snowplow Micro:

    gdk config set snowplow_micro.enabled true

  3. Optional. Snowplow Micro runs on port 9091 by default, you can change to 9092 by running:

    gdk config set snowplow_micro.port 9092

  4. Regenerate your Procfile and YAML config by reconfiguring GDK:

    gdk reconfigure

  5. Restart the GDK:

    gdk restart

  6. You can now see all events being sent by your local instance in the Snowplow Micro UI and can filter for specific events.

Configure a remote event collector

On GitLab.com events are sent to a collector configured by GitLab. By default, self-managed instances do not have a collector configured and do not collect data with Snowplow.

You can configure your self-managed GitLab instance to use a custom Snowplow collector.

  1. On the left sidebar, select Search or go to.
  2. Select Admin Area.
  3. On the left sidebar, select Settings > General.
  4. Expand Snowplow.

  5. Select Enable Snowplow tracking and enter your Snowplow configuration information. For example:

    NameValue
    Collector hostnameyour-snowplow-collector.net
    App IDgitlab
    Cookie domain.your-gitlab-instance.com
  6. Select Save changes.

Snowplow Analytics Debugger Chrome Extension

Snowplow Analytics Debugger is a browser extension for testing frontend events. It works in production, staging, and local development environments. It is especially suited to verifying correct events are getting sent in a deployed environment.

  1. Install the Snowplow Analytics Debugger Chrome browser extension.
  2. Open Chrome DevTools to the Snowplow Debugger tab.
  3. Any event triggered on a GitLab page should appear in the Snowplow Debugger tab.