Implement Snowplow tracking

This page describes how to:

• Implement Snowplow frontend and backend tracking
• Test Snowplow events

Event definitions

Every Snowplow event, regardless of frontend or backend, requires a corresponding event definition. These definitions document the event and its properties to make it easier to maintain and analyze. These definitions can be browsed in the event dictionary. The event dictionary guide provides instructions for setting up an event definition.

Snowplow JavaScript frontend tracking

GitLab provides a Tracking interface that wraps the Snowplow JavaScript tracker to track custom events.

For the recommended frontend tracking implementation, see Usage recommendations.

Structured events and page views include the gitlab_standard context, using the window.gl.snowplowStandardContext object which includes default data as base:

* Undergoes a pseudonymization process at the collector level.

These properties are overridden with frontend-specific values, like source (gitlab-javascript), google_analytics_id and the custom extra object. You can modify this object for any subsequent structured event that fires, although this is not recommended.

Tracking implementations must have an action and a category. You can provide additional properties from the event schema, in addition to an extra object that accepts key-value pairs.

Usage recommendations

• Use data attributes on HTML elements that emit click, show.bs.dropdown, or hide.bs.dropdown events.
• Use the Vue mixin for tracking custom events, or if the supported events for data attributes are not propagating. For example, clickable components that don't emit click.
• Use the tracking class when tracking in vanilla JavaScript files.

Implement data attribute tracking

To implement tracking for HAML or Vue templates, add a data-track attribute to the element.

The following example shows data-track-* attributes assigned to a button:

%button.btn{ data: { track_action: "click_button", track_label: "template_preview", track_property: "my-template" } }

<button class="btn"
  data-track-action="click_button"
  data-track-label="template_preview"
  data-track-property="my-template"
  data-track-extra='{ "template_variant": "primary" }'
/>

data-track attributes

Event listeners

Event listeners bind at the document level to handle click events in elements with data attributes. This allows them to be handled when the DOM re-renders or changes. Document-level binding reduces the likelihood that click events stop propagating up the DOM tree.

If click events stop propagating, you must implement listeners and Vue component tracking or raw JavaScript tracking.

Helper methods

You can use the following Ruby helpers:

tracking_attrs(label, action, property) # { data: { track_label... } }

tracking_attrs_data(label, action, property) # { track_label... }

You can also use it on HAML templates:

%button{ **tracking_attrs('main_navigation', 'click_button', 'navigation') }

// When merging with additional data
// %button{ data: { platform: "...", **tracking_attrs_data('main_navigation', 'click_button', 'navigation') } }

If you use the GitLab helper method nav_link, you must wrap html_options under the html_options keyword argument. If you use the ActionView helper method link_to, you don't need to wrap html_options.

# Bad
= nav_link(controller: ['dashboard/groups', 'explore/groups'], data: { track_label: "explore_groups",
track_action: "click_button" })

# Good
= nav_link(controller: ['dashboard/groups', 'explore/groups'], html_options: { data: { track_label:
"explore_groups", track_action: "click_button" } })

# Good (other helpers)
= link_to explore_groups_path, title: _("Explore"), data: { track_label: "explore_groups", track_action:
"click_button" }

Implement Vue component tracking

For custom event tracking, use the Vue mixin. It exposes Tracking.event as the track method. You can specify tracking options by creating a tracking data object or computed property, and as a second parameter: this.track('click_button', opts). These options override any defaults and allow the values to be dynamic from props or based on state:

To implement Vue component tracking:

1. Import the Tracking library and call the mixin method:

   import Tracking from '~/tracking';
   
   const trackingMixin = Tracking.mixin();
   
   // Optionally provide default properties
   // const trackingMixin = Tracking.mixin({ label: 'right_sidebar' });

2. Use the mixin in the component:

   export default {
     mixins: [trackingMixin],
     // Or
     // mixins: [Tracking.mixin()],
     // mixins: [Tracking.mixin({ label: 'right_sidebar' })],
   
     data() {
       return {
         expanded: false,
       };
     },
   };

3. You can specify tracking options in by creating a tracking data object or computed property:

   export default {
     name: 'RightSidebar',
   
     mixins: [Tracking.mixin()],
   
     data() {
       return {
         expanded: false,
         variant: '',
         tracking: {
           label: 'right_sidebar',
           // property: '',
           // value: '',
           // experiment: '',
           // extra: {},
         },
       };
     },
   
     // Or
     // computed: {
     //   tracking() {
     //     return {
     //       property: this.variant,
     //       extra: { expanded: this.expanded },
     //     };
     //   },
     // },
   };

4. Call the track method. Tracking options can be passed as the second parameter:

   this.track('click_button', {
     label: 'right_sidebar',
   });

   Or use the track method in the template:

   <template>
     <div>
       <button data-testid="toggle" @click="toggle">Toggle</button>
   
       <div v-if="expanded">
         <p>Hello world!</p>
         <button @click="track('click_button')">Track another event</button>
       </div>
     </div>
   </template>

Testing example

export default {
  name: 'CountDropdown',

  mixins: [Tracking.mixin({ label: 'count_dropdown' })],

  data() {
    return {
      variant: 'counter',
      count: 0,
    };
  },

  methods: {
    handleChange({ target }) {
      const { variant } = this;

      this.count = Number(target.value);

      this.track('change_value', {
        value: this.count,
        extra: { variant }
      });
    },
  },
};

import { mockTracking } from 'helpers/tracking_helper';
// mockTracking(category, documentOverride, spyMethod)

describe('CountDropdown.vue', () => {
  let trackingSpy;
  let wrapper;

  ...

  beforeEach(() => {
    trackingSpy = mockTracking(undefined, wrapper.element, jest.spyOn);
  });

  const findDropdown = () => wrapper.find('[data-testid="dropdown"]');

  it('tracks change event', () => {
    const dropdown = findDropdown();
    dropdown.element.value = 30;
    dropdown.trigger('change');

    expect(trackingSpy).toHaveBeenCalledWith(undefined, 'change_value', {
      value: 30,
      label: 'count_dropdown',
      extra: { variant: 'counter' },
    });
  });
});

Implement raw JavaScript tracking

To track from a vanilla JavaScript file, use the Tracking.event static function (calls dispatchSnowplowEvent).

The following example demonstrates tracking a click on a button by manually calling Tracking.event.

import Tracking from '~/tracking';

const button = document.getElementById('create_from_template_button');

button.addEventListener('click', () => {
  Tracking.event(undefined, 'click_button', {
    label: 'create_from_template',
    property: 'template_preview',
    extra: {
      templateVariant: 'primary',
      valid: 1,
    },
  });
});

Testing example

import Tracking from '~/tracking';

describe('MyTracking', () => {
  let wrapper;

  beforeEach(() => {
    jest.spyOn(Tracking, 'event');
  });

  const findButton = () => wrapper.find('[data-testid="create_from_template"]');

  it('tracks event', () => {
    findButton().trigger('click');

    expect(Tracking.event).toHaveBeenCalledWith(undefined, 'click_button', {
      label: 'create_from_template',
      property: 'template_preview',
      extra: {
        templateVariant: 'primary',
        valid: true,
      },
    });
  });
});

Form tracking

To enable Snowplow automatic form tracking:

1. Call Tracking.enableFormTracking when the DOM is ready.
2. Provide a config object that includes at least one of the following elements:
   • forms determines the forms to track. Identified by the CSS class name.
   • fields determines the fields inside the tracked forms to track. Identified by the field name.
3. Optional. Provide a list of contexts as the second argument. The gitlab_standard schema is excluded from these events.

Tracking.enableFormTracking({
  forms: { allow: ['sign-in-form', 'password-recovery-form'] },
  fields: { allow: ['terms_and_conditions', 'newsletter_agreement'] },
});

Testing example

import Tracking from '~/tracking';

describe('MyFormTracking', () => {
  let formTrackingSpy;

  beforeEach(() => {
    formTrackingSpy = jest
      .spyOn(Tracking, 'enableFormTracking')
      .mockImplementation(() => null);
  });

  it('initialized with the correct configuration', () => {
    expect(formTrackingSpy).toHaveBeenCalledWith({
      forms: { allow: ['sign-in-form', 'password-recovery-form'] },
      fields: { allow: ['terms_and_conditions', 'newsletter_agreement'] },
    });
  });
});

Implement Ruby backend tracking

Gitlab::Tracking is an interface that wraps the Snowplow Ruby Tracker for tracking custom events. Backend tracking provides:

• User behavior tracking
• Instrumentation to monitor and visualize performance over time in a section or aspect of code.

To add custom event tracking and instrumentation, call the GitLab::Tracking.event class method. For example:

class Projects::CreateService < BaseService
  def execute
    project = Project.create(params)

    Gitlab::Tracking.event('Projects::CreateService', 'create_project', label: project.errors.full_messages.to_sentence,
                           property: project.valid?.to_s, project: project, user: current_user, namespace: namespace)
  end
end

Use the following arguments:

Unit testing

To test backend Snowplow events, use the expect_snowplow_event helper. For more information, see testing best practices.

Performance

We use the AsyncEmitter when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development.

Develop and test Snowplow

To develop and test a Snowplow event, there are several tools to test frontend and backend events:

Test frontend events

Before you test frontend events in development, you must:

1. Enable Snowplow tracking in the Admin Area.
2. Turn off ad blockers that could prevent Snowplow JavaScript from loading in your environment.
3. Turn off "Do Not Track" (DNT) in your browser.

All URLs are pseudonymized. The entity identifier replaces personally identifiable information (PII). PII includes usernames, group, and project names. Page titles are hardcoded as GitLab for the same reason.

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.

1. Install the Snowplow Analytics Debugger Chrome browser extension.
2. Open Chrome DevTools to the Snowplow Analytics Debugger tab.

Snowplow Inspector Chrome Extension

Snowplow Inspector Chrome Extension is a browser extension for testing frontend events. This works in production, staging, and local development environments.

For a video tutorial, see the Snowplow plugin walk through.

1. Install Snowplow Inspector.
2. To open the extension, select the Snowplow Inspector icon beside the address bar.
3. Click around on a webpage with Snowplow to see JavaScript events firing in the inspector window.

Test backend events with Snowplow Micro

Snowplow Micro is a Docker-based solution for testing backend and frontend in a local development environment. Snowplow Micro records the same events as the full Snowplow pipeline. To query events, use the Snowplow Micro API.

It can be set up automatically using GitLab Development Kit (GDK). See the how-to docs for more details.

1. Set the environment variable to tell the GDK to use Snowplow Micro in development. This overrides two application_settings options:

   • snowplow_enabled setting will instead return true from Gitlab::Tracking.enabled?
   • snowplow_collector_hostname setting will instead always return localhost:9090 (or whatever port is set for snowplow_micro.port GDK setting) from Gitlab::Tracking.collector_hostname. With Snowplow Micro set up you can now manually test backend Snowplow events:

2. Send a test Snowplow event from the Rails console:

   Gitlab::Tracking.event('category', 'action')

3. Navigate to localhost:9090/micro/good to see the event.

Useful links

• Snowplow Micro repository
• Installation guide recording

Troubleshoot

To control content security policy warnings when using an external host, modify config/gitlab.yml to allow or prevent them. To allow them, add the relevant host for connect_src. For example, for https://snowplow.trx.gitlab.net:

development:
  <<: *base
  gitlab:
    content_security_policy:
      enabled: true
      directives:
        connect_src: "'self' http://localhost:* http://127.0.0.1:* ws://localhost:* wss://localhost:* ws://127.0.0.1:* https://snowplow.trx.gitlab.net/"