From 6bb568ff0c553527cd358b8f6be0a11d64530d40 Mon Sep 17 00:00:00 2001
From: Niko Belokolodov <nbelokolodov@gitlab.com>
Date: Mon, 5 Aug 2024 04:19:19 +0000
Subject: [PATCH] Add documentation related to additional properties in
Internal Events
---
.../event_definition_guide.md | 1 +
.../quick_start.md | 25 ++++++++++++++++++-
2 files changed, 25 insertions(+), 1 deletion(-)
diff --git a/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md b/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md
index 0d706b39e42c5..24de9622aa8d3 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md
@@ -34,6 +34,7 @@ Each event is defined in a separate YAML file consisting of the following fields
| `introduced_by_url` | no | The URL to the merge request that introduced the event. |
| `distributions` | yes | The [distributions](https://handbook.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/tiers/#definitions) where the tracked feature is available. Can be set to one or more of `ce` or `ee`. |
| `tiers` | yes | The [tiers](https://handbook.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/tiers/) where the tracked feature is available. Can be set to one or more of `free`, `premium`, or `ultimate`. |
+| `additional_properties` | no | A list of additional properties that are sent with the event. Each record must have `description` field. Built-in properties are: `label` (string), `property` (string) and `value` (numeric). [Custom](quick_start.md#additional-properties) properties can be added if the built-in options are not sufficient. |
### Example event definition
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 319c629d147ea..5b11531579150 100644
--- a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
+++ b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md
@@ -76,7 +76,10 @@ track_internal_event(
#### 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 with keys `label` (string), `property` (string) and `value`(numeric).
+Additional properties can be passed when tracking events. They can be used to save additional data related to given event.
+
+Tracking classes have built-in properties with keys `label` (string), `property` (string) and `value`(numeric). It's recommended
+to use these properties first.
Additional properties are passed by including the `additional_properties` hash in the `#track_event` call:
@@ -91,6 +94,26 @@ track_internal_event(
)
```
+If you need to pass more than three additional properties, you can use the `additional_properties` hash with your custom keys:
+
+```ruby
+track_internal_event(
+ "code_suggestion_accepted",
+ user: user,
+ additional_properties: {
+ label: 'vsc',
+ property: 'automatic',
+ value: 200,
+ lang: 'ruby',
+ custom_key: 'custom_value'
+ }
+)
+```
+
+Please add custom properties only in addition to the built-in properties.
+
+Custom rules can not be used as [metric filters](metric_definition_guide.md#filters).
+
#### 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`:
--
GitLab