1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
---
stage: Analyze
group: Analytics Instrumentation
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# 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
1. Define one or more metrics
1. Trigger the event
## Defining event and metrics
<div class="video-fallback">
See the video about <a href="https://www.youtube.com/watch?v=QICKWznLyy0">adding events and metrics using the generator</a>
</div>
<figure class="video_container">
<iframe src="https://www.youtube-nocookie.com/embed/QICKWznLyy0" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
To create an event and metric definitions you can use the `internal_events` generator.
This example creates an event definition for an event called `project_created` and two metric definitions, which are aggregated every 7 and 28 days.
```shell
bundle exec rails generate gitlab:analytics:internal_events \
--time_frames=7d 28d \
--group=project_management \
--stage=plan \
--section=dev \
--event=project_created \
--unique=user.id \
--mr=https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121544
```
Where:
- `time_frames`: Valid options are `7d` and `28d` if you provide a `unique` value and `all` for metrics without `unique`. We are working to make `7d` and `28d` work for metrics with `all` time frame in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411264).
- `unique`: Valid options are `user.id`, `project.id`, and `namespace.id`, as they are logged as part of the standard context. We [are actively working](https://gitlab.com/gitlab-org/gitlab/-/issues/411255) on a way to define uniqueness on arbitrary properties sent with the event, such as `merge_request.id`.
## Trigger events
Triggering an event and thereby updating a metric is slightly different on backend and frontend. Please refer to the relevant section below.
### Backend tracking
To trigger an event, call the `Gitlab::InternalEvents.track_event` method with the desired arguments:
```ruby
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).
### Frontend tracking
#### Vue components
In Vue components, tracking can be done with [Vue mixin](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/internal_events.js#L29).
To implement Vue component tracking:
1. Import the `InternalEvents` library and call the `mixin` method:
```javascript
import { InternalEvents } from '~/tracking';
const trackingMixin = InternalEvents.mixin();
```
1. Use the mixin in the component:
```javascript
export default {
mixins: [trackingMixin],
data() {
return {
expanded: false,
};
},
};
```
1. Call the `trackEvent` method. Tracking options can be passed as the second parameter:
```javascript
this.trackEvent('i_code_review_user_apply_suggestion');
```
Or use the `trackEvent` method in the template:
```html
<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.
```javascript
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.
```html
<gl-button
data-event-tracking="i_analytics_dev_ops_adoption"
>
Click Me
</gl-button>
```
#### Haml
```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:
```haml
= render Pajamas::ButtonComponent.new(button_options: { data: { event_tracking_load: 'true', event_tracking: 'i_devops' } }) do
= _("New project")
```
|
