Migrating existing tracking to internal event tracking
GitLab Internal Events Tracking exposes a unified API on top of the deprecated Snowplow and Redis/RedisHLL event tracking options.
This page describes how you can switch from one of the previous methods to using Internal Events Tracking.
Migrating from existing Snowplow tracking
If you are already tracking events in Snowplow, you can also start collecting metrics from self-managed instances by switching to Internal Events Tracking.
The event triggered by Internal Events has some special properties compared to previously tracking with Snowplow directly:
- The
label
,property
andvalue
attributes are not used within Internal Events and are always empty. - The
category
is automatically set toInternalEventTracking
Please make sure that you are okay with this change before you migrate and dashboards are changed accordingly.
Backend
If you are already tracking Snowplow events using Gitlab::Tracking.event
and you want to migrate to Internal Events Tracking you might start with something like this:
Gitlab::Tracking.event(name, 'ci_templates_unique', namespace: namespace,
project: project, context: [context], user: user, label: label)
The code above can be replaced by this:
Gitlab::InternalEvents.track_event('ci_templates_unique', namespace: namespace, project: project, user: user)
In addition, you have to create definitions for the metrics that you would like to track.
To generate metric definitions, you can use the generator like this:
bin/rails g gitlab:analytics:internal_events \
--time_frames=7d 28d\
--group=project_management \
--stage=plan \
--section=dev \
--event=ci_templates_unique \
--unique=user.id \
--mr=https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121544
Frontend
If you are using the Tracking
mixin in the Vue component, you can replace it with the InternalEvents
mixin.
For example, if your current Vue component look like this:
import Tracking from '~/tracking';
...
mixins: [Tracking.mixin()]
...
...
this.track('some_label', options)
After converting it to Internal Events Tracking, it should look like this:
import { InternalEvents } from '~/tracking';
...
mixins: [InternalEvents.mixin()]
...
...
this.trackEvent('action')
You can use this MR as an example. It migrates the devops_adoption_app
component to use Internal Events Tracking.
If you are using data-track-action
in the component, you have to change it to data-event-tracking
to migrate to Internal Events Tracking.
For example, if a button is defined like this:
<gl-button
:href="diffFile.external_url"
:title="externalUrlLabel"
:aria-label="externalUrlLabel"
target="_blank"
data-track-action="click_toggle_external_button"
data-track-label="diff_toggle_external_button"
data-track-property="diff_toggle_external"
icon="external-link"
/>
This can be converted to Internal Events Tracking like this:
<gl-button
:href="diffFile.external_url"
:title="externalUrlLabel"
:aria-label="externalUrlLabel"
target="_blank"
data-event-tracking="click_toggle_external_button"
icon="external-link"
/>
Notice that we just need action to pass in the data-event-tracking
attribute which will be passed to both Snowplow and RedisHLL.
Migrating from tracking with RedisHLL
Backend
If you are currently tracking a metric in RedisHLL
like this:
Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id)
To start using Internal Events Tracking, follow these steps:
- Create an event definition that describes
git_write_action
(guide). - Find metric definitions that list
git_write_action
in the events section (20210216182041_action_monthly_active_users_git_write.yml
and20210216184045_git_write_action_weekly.yml
). - Change the
data_source
fromredis_hll
tointernal_events
in the metric definition files. -
Add an
events
section to both metric definition files.events: - name: git_write_action unique: user.id
Use
project.id
ornamespace.id
instead ofuser.id
if your metric is counting something other than unique users. -
Call
InternalEvents.tract_event
instead ofHLLRedisCounter.track_event
:- Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id) + Gitlab::InternalEvents.track_event('project_created', user: current_user)
-
Optional. Add additional values to the event. You typically want to add
project
andnamespace
as it is useful information to have in the data warehouse.- Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id) + Gitlab::InternalEvents.track_event('project_created', user: current_user, project: project, namespace: namespace)
- Update your test to use the
internal event tracking
shared example.
Frontend
If you are calling trackRedisHllUserEvent
in the frontend to track the frontend event, you can convert this to Internal events by using mixin, raw JavaScript or data tracking attribute,
Quick start guide has example for each methods.