From 1f406ce6a8641a9d8a54c88e94afff516155d10f Mon Sep 17 00:00:00 2001
From: Jonas Larsen <jlarsen@gitlab.com>
Date: Fri, 1 Mar 2024 13:57:41 +0000
Subject: [PATCH] Add documentation for InternalEventsTracking module
---
.../internal_event_instrumentation/migration.md | 12 ++++++++----
.../quick_start.md | 9 +++++++--
scripts/internal_events/cli/text.rb | 3 ++-
scripts/internal_events/cli/usage_viewer.rb | 4 +++-
spec/scripts/internal_events/cli_spec.rb | 16 ++++++++++++----
5 files changed, 32 insertions(+), 12 deletions(-)
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/migration.md b/doc/development/internal_analytics/internal_event_instrumentation/migration.md
index 6cb43ddebbb79..e9859b0850267 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/migration.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/migration.md
@@ -37,7 +37,9 @@ Gitlab::Tracking.event(name, 'ci_templates_unique', namespace: namespace,
The code above can be replaced by this:
```ruby
-Gitlab::InternalEvents.track_event('ci_templates_unique', namespace: namespace, project: project, user: user, additional_properties: { label: label })
+include Gitlab::InternalEventsTracking
+
+track_internal_event('ci_templates_unique', namespace: namespace, project: project, user: user, additional_properties: { label: label })
```
The `label`, `property` and `value` attributes need to be sent inside the `additional_properties` hash. In case they were not included in the original call, the `additional_properties` argument can be skipped.
@@ -140,18 +142,20 @@ To start using Internal Events Tracking, follow these steps:
Use `project.id` or `namespace.id` instead of `user.id` if your metric is counting something other than unique users.
1. Remove the `options` section from both metric definition files.
-1. Call `InternalEvents.track_event` instead of `HLLRedisCounter.track_event`:
+1. Include the `Gitlab::InternalEventsTracking` module and call `track_internal_event` instead of `HLLRedisCounter.track_event`:
```diff
- Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id)
- + Gitlab::InternalEvents.track_event('project_created', user: current_user)
+ + include Gitlab::InternalEventsTracking
+ + track_internal_event('project_created', user: current_user)
```
1. Optional. Add additional values to the event. You typically want to add `project` and `namespace` as it is useful information to have in the data warehouse.
```diff
- 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)
+ + include Gitlab::InternalEventsTracking
+ + track_internal_event('project_created', user: current_user, project: project, namespace: namespace)
```
1. Update your test to use the `internal event tracking` shared example.
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
index e23366e02acb4..b152d98b23757 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
@@ -38,10 +38,12 @@ Triggering an event and thereby updating a metric is slightly different on backe
<iframe src="https://www.youtube-nocookie.com/embed/Teid7o_2Mmg" frameborder="0" allowfullscreen> </iframe>
</figure>
-To trigger an event, call the `Gitlab::InternalEvents.track_event` method with the desired arguments:
+To trigger an event, call the `track_internal_event` method from the `Gitlab::InternalEventsTracking` module with the desired arguments:
```ruby
-Gitlab::InternalEvents.track_event(
+include Gitlab::InternalEventsTracking
+
+track_internal_event(
"i_code_review_user_apply_suggestion",
user: user,
namespace: namespace,
@@ -50,6 +52,7 @@ Gitlab::InternalEvents.track_event(
```
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).
+In addition, the name of the class triggering the event is saved in the `category` property of the Snowplow event.
If you have defined a metric with a `unique` property such as `unique: project.id` it is required that you provide the `project` argument.
@@ -57,6 +60,8 @@ It is encouraged to fill out as many of `user`, `namespace` and `project` as pos
If a `project` but no `namespace` is provided, the `project.namespace` is used as the `namespace` for the event.
+In some cases you might want to specify the `category` manually or provide none at all. To do that, you can call the `InternalEvents.track_event` method directly instead of using the module.
+
#### Additional properties
Additional properties can be passed when tracking events. They can be used to save additional data related to given event. It is possible to send a maximum of three additional properties (2 string and 1 numeric attribute).
diff --git a/scripts/internal_events/cli/text.rb b/scripts/internal_events/cli/text.rb
index 88145120c0ab2..e524b879d3800 100755
--- a/scripts/internal_events/cli/text.rb
+++ b/scripts/internal_events/cli/text.rb
@@ -157,8 +157,9 @@ module Text
#{format_info('BACKEND')}: Attributes must be specified when the event is triggered
ex) User, project, and namespace are the identifiers available for backend instrumentation:
+ include Gitlab::InternalEventsTracking
- Gitlab::InternalEvents.track_event(
+ track_internal_event(
'%s',
user: user,
project: project,
diff --git a/scripts/internal_events/cli/usage_viewer.rb b/scripts/internal_events/cli/usage_viewer.rb
index 6a9be38e25d78..fdb4303b6db70 100755
--- a/scripts/internal_events/cli/usage_viewer.rb
+++ b/scripts/internal_events/cli/usage_viewer.rb
@@ -97,7 +97,9 @@ def rails_examples
#{divider}
#{format_help('# RAILS')}
- Gitlab::InternalEvents.track_event(#{action}#{args.join(",\n")}#{"\n" unless args.empty?})
+ include Gitlab::InternalEventsTracking
+
+ track_internal_event(#{action}#{args.join(",\n")}#{"\n" unless args.empty?})
#{divider}
TEXT
diff --git a/spec/scripts/internal_events/cli_spec.rb b/spec/scripts/internal_events/cli_spec.rb
index 1c7a5e924a2fb..4ea87d3a5a335 100644
--- a/spec/scripts/internal_events/cli_spec.rb
+++ b/spec/scripts/internal_events/cli_spec.rb
@@ -398,7 +398,9 @@ def select_event_from_list
--------------------------------------------------
# RAILS
- Gitlab::InternalEvents.track_event(
+ include Gitlab::InternalEventsTracking
+
+ track_internal_event(
'internal_events_cli_used',
project: project,
namespace: project.namespace,
@@ -456,7 +458,9 @@ def select_event_from_list
--------------------------------------------------
# RAILS
- Gitlab::InternalEvents.track_event('internal_events_cli_opened')
+ include Gitlab::InternalEventsTracking
+
+ track_internal_event('internal_events_cli_opened')
--------------------------------------------------
TEXT
@@ -627,7 +631,9 @@ def select_event_from_list
--------------------------------------------------
# RAILS
- Gitlab::InternalEvents.track_event(
+ include Gitlab::InternalEventsTracking
+
+ track_internal_event(
'internal_events_cli_used',
project: project,
namespace: project.namespace,
@@ -643,7 +649,9 @@ def select_event_from_list
--------------------------------------------------
# RAILS
- Gitlab::InternalEvents.track_event('internal_events_cli_opened')
+ include Gitlab::InternalEventsTracking
+
+ track_internal_event('internal_events_cli_opened')
--------------------------------------------------
TEXT
--
GitLab