<details><summary>Minimal steps to fire a Snowplow event as of Nov 2021</summary> <br> (based on the [usage recommendations for frontend](https://docs.gitlab.com/ee/development/snowplow/implementation.html#usage-recommendations)) ```html <!-- Using data-attributes --> <button data-track-action="click_button" /> ``` ```js // Using Vue import Tracking from '~/tracking'; ... mixins: [Tracking.mixin()], ... this.track('click_button', { label: 'submit' }); // Using raw JS import Tracking from '~/tracking'; Tracking.event(undefined, 'click_button', { label: 'submit' }); ``` </details> ---- ### Proposal #### Background [Snowplow event definitions](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/events), as the source of the [Event Dictionary](https://metrics.gitlab.com/snowplow.html), are independent of the actual event in the code. So coupling an event with its definition becomes a problematic task, evidenced by the completed work on https://gitlab.com/groups/gitlab-org/-/epics/5247. So we would need to implement -mostly manual- maintenance measures to avoid outdated or incorrect definitions. Additionally, the event definition contains metadata ([example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/events/20210915205037_alert_integrations_view_alert_integrations_list.yml#L4-21)) that is not stored or referenced by the event directly. So accessing this metadata from the data warehouse would be complex and implausible to automate. #### Proposed solution Allow firing a Snowplow event with its base data coming from an event definition. Example with placeholder API (naming also TDB): <details><summary>Example definition</summary> <br> <small><b>config/events/20210915205040_default_generic.yml</b></small> ```yml description: "Show a congratulation message on first pipeline" category: default action: generic label_description: "`congratulate_first_pipeline`" property_description: "`[admin | maintainer | developer | owner]`" value_description: "" extra_properties: identifiers: product_section: growth product_stage: growth product_group: group::expansion product_category: milestone: "12.10" introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28378 distributions: - ce - ee tiers: - free - premium - ultimate ``` </details> ```html <!-- Using data-attributes --> <button data-track-definition="20210915205040_default_generic" /> ``` ```js // Using Vue import Tracking from '~/tracking'; ... mixins: [Tracking.mixin()], ... this.trackDefinition('20210915205040_default_generic', { label: 'submit' }); // Using raw JS import Tracking from '~/tracking'; Tracking.definition('20210915205040_default_generic', { label: 'submit' }); ``` </details> #### Details to consider - Using a unique event key/name would improve the implementation. Similar to [Metrics naming conventions](https://docs.gitlab.com/ee/development/service_ping/metrics_dictionary.html#metric-name). - Finding the matching definition for an event would be trivial on the backend, but it might be tricky on the frontend. We might need to implement a preload step after event discovery, which seems plausible with the javascript implementation. #### Benefits/Wins - We would be able to link an event in the data warehouse with its definition. - This would keep the event dictionary up-to-date, although we would need to consider some kind of versioning for historical reasons. - We would have access to the static data related to an event, that we don’t send at the moment, like `label_description`, `property_description`, `value_description`, `identifiers`, `product_section`, `product_stage`, `product_group`, `product_category`, `milestone`, `introduced_by_url`, `distributions`, `tiers`. - We would be able to add more non-automatic fields to the `gitlab_standard` (or other) schema, like a `product_group` property to filter events by owners in the data warehouse.