Quick start for Internal Event Tracking

In an effort to provide a more efficient, scalable, and unified tracking API, GitLab is deprecating existing RedisHLL and Snowplow tracking. Instead, we're implementing a new track_event (Backend) and trackEvent(Frontend) method. With this approach, we can update both RedisHLL counters and send Snowplow events without worrying about the underlying implementation.

In order to instrument your code with Internal Events Tracking you need to do three things:

1. Define an event
2. Define one or more metrics
3. Trigger the event

Defining event and metrics

To create event and/or metric definitions, use the internal_events generator from the gitlab directory:

ruby scripts/internal_events/cli.rb

This CLI will help you create the correct defintion files based on your specific use-case, then provide code examples for instrumentation and testing.

Trigger events

Triggering an event and thereby updating a metric is slightly different on backend and frontend. Refer to the relevant section below.

Backend tracking

To trigger an event, call the Gitlab::InternalEvents.track_event method with the desired arguments:

Gitlab::InternalEvents.track_event(
  "i_code_review_user_apply_suggestion",
  user: user,
  namespace: namespace,
  project: project
)

This method automatically increments all RedisHLL metrics relating to the event i_code_review_user_apply_suggestion, and sends a corresponding Snowplow event with all named arguments and standard context (SaaS only).

If you have defined a metric with a unique property such as unique: project.id it is required that you provide the project argument.

It is encouraged to fill out as many of user, namespace and project as possible as it increases the data quality and make it easier to define metrics in the future.

If a project but no namespace is provided, the project.namespace is used as the namespace for the event.

Controller and API helpers

There is a helper module ProductAnalyticsTracking for controllers you can use to track internal events for particular controller actions by calling #track_internal_event:

class Projects::PipelinesController < Projects::ApplicationController
  include ProductAnalyticsTracking

  track_internal_event :charts, name: 'p_analytics_ci_cd_pipelines', conditions: -> { should_track_ci_cd_pipelines? }

  def charts
    ...
  end

  private

  def should_track_ci_cd_pipelines?
    params[:chart].blank? || params[:chart] == 'pipelines'
  end
end

You need to add these two methods to the controller body, so that the helper can get the current project and namespace for the event:

  private

  def tracking_namespace_source
    project.namespace
  end

  def tracking_project_source
    project
  end

Also, there is an API helper:

track_event(
  event_name,
  user: current_user,
  namespace_id: namespace_id,
  project_id: project_id
)

Frontend tracking

Any frontend tracking call automatically passes the values user.id, namespace.id, and project.id from the current context of the page.

If you need to pass any further properties, such as extra, context, label, property, and value, you can use the deprecated snowplow implementation. In this case, let us know about your specific use-case in our feedback issue for Internal Events.

Vue components

In Vue components, tracking can be done with Vue mixin.

To implement Vue component tracking:

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

   import { InternalEvents } from '~/tracking';
   const trackingMixin = InternalEvents.mixin();

2. Use the mixin in the component:

   export default {
     mixins: [trackingMixin],
   
     data() {
       return {
         expanded: false,
       };
     },
   };

3. Call the trackEvent method. Tracking options can be passed as the second parameter:

   this.trackEvent('i_code_review_user_apply_suggestion');

   Or use the trackEvent method in the template:

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

Raw JavaScript

For tracking events directly from arbitrary frontend JavaScript code, a module for raw JavaScript is provided. This can be used outside of a component context where the Mixin cannot be utilized.

import { InternalEvents } from '~/tracking';
InternalEvents.trackEvent('i_code_review_user_apply_suggestion');

Data-track attribute

This attribute ensures that if we want to track GitLab internal events for a button, we do not need to write JavaScript code on Click handler. Instead, we can just add a data-event-tracking attribute with event value and it should work. This can also be used with HAML views.

  <gl-button
    data-event-tracking="i_analytics_dev_ops_adoption"
  >
   Click Me
  </gl-button>

Haml

= render Pajamas::ButtonComponent.new(button_options: { class: 'js-settings-toggle',  data: { event_tracking: 'action' }}) do

Internal events on render

Sometimes we want to send internal events when the component is rendered or loaded. In these cases, we can add the data-event-tracking-load="true" attribute:

= render Pajamas::ButtonComponent.new(button_options: { data: { event_tracking_load: 'true', event_tracking: 'i_devops' } }) do
        = _("New project")