Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42

3 files changed, 148 insertions, 9 deletions

diff --git a/doc/development/snowplow/dictionary.md b/doc/development/snowplow/dictionary.md
new file mode 100644
index 00000000000..f20ec41d558
--- /dev/null
+++ b/doc/development/snowplow/dictionary.md
@@ -0,0 +1,44 @@
+---
+stage: Growth
+group: Product Intelligence
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+<!---
+  This documentation is auto generated by a script.
+
+  Please do not edit this file directly, check generate_metrics_dictionary task on lib/tasks/gitlab/usage_data.rake.
+--->
+
+<!-- vale gitlab.Spelling = NO -->
+
+# Event Dictionary
+
+This file is autogenerated, please do not edit it directly.
+
+To generate these files from the GitLab repository, run:
+
+```shell
+bundle exec rake gitlab:snowplow:generate_event_dictionary
+```
+
+The Event Dictionary is based on the following event definition YAML files:
+
+- [`config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/f9a404301ca22d038e7b9a9eb08d9c1bbd6c4d84/config/events)
+- [`ee/config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/f9a404301ca22d038e7b9a9eb08d9c1bbd6c4d84/ee/config/events)
+
+## Event definitions
+
+### `epics promote`
+
+| category | action | label | property | value |
+|---|---|---|---|---|
+| `epics` | `promote` | `` | `The string "issue_id"` | `ID of the issue` |
+
+Issue promoted to epic
+
+YAML definition: `/ee/config/events/epics_promote.yml`
+
+Owner: `group::product planning`
+
+Tiers: `premium`, `ultimate`
diff --git a/doc/development/snowplow/event_dictionary_guide.md b/doc/development/snowplow/event_dictionary_guide.md
new file mode 100644
index 00000000000..5ae81c3426d
--- /dev/null
+++ b/doc/development/snowplow/event_dictionary_guide.md
@@ -0,0 +1,94 @@
+---
+stage: Growth
+group: Product Intelligence
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Event dictionary guide
+
+NOTE:
+The event dictionary is a work in progress, and this process is subject to change.
+
+This guide describes the event dictionary and how it's implemented.
+
+## Event definition and validation
+
+This process is meant to document all Snowplow events and ensure consistency. Event definitions must comply with the [JSON Schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/events/schema.json).
+
+All event definitions are stored in the following directories:
+
+- [`config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/events)
+- [`ee/config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/events)
+
+Each event is defined in a separate YAML file consisting of the following fields:
+
+| Field                  | Required | Additional information                                                                                                                                          |
+|------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `description`          | yes      | A description of the event.                                                                                                                                        |
+| `category`             | yes      | The event category (see [Structured event taxonomy](index.md#structured-event-taxonomy)).                                                  |
+| `action`               | yes      | The event action (see [Structured event taxonomy](index.md#structured-event-taxonomy)).                                                    |
+| `label_description`    | no       | A description of the event label (see [Structured event taxonomy](index.md#structured-event-taxonomy)).                                      |
+| `property_description` | no       | A description of the event property (see [Structured event taxonomy](index.md#structured-event-taxonomy)).                                   |
+| `value_description`    | no       | A description of the event value (see [Structured event taxonomy](index.md#structured-event-taxonomy)).                                      |
+| `extra_properties`     | no       | The type and description of each extra property sent with the event.                                                                                                 |
+| `identifiers`          | no       | A list of identifiers sent with the event. Can be set to one or more of `project`, `user`, or `namespace`.                                                                                    |
+| `iglu_schema_url`      | no       | The URL to the custom schema sent with the event, for example, `iglu:com.gitlab/gitlab_experiment/jsonschema/1-0-0`.                                                         |
+| `product_section`      | yes      | The [section](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/sections.yml).                                                                    |
+| `product_stage`        | no       | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the event.                                                             |
+| `product_group`        | yes      | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the event.                                                       |
+| `product_category`     | no       | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the event.                                              |
+| `milestone`            | no       | The milestone when the event is introduced.                                                                                                                      |
+| `introduced_by_url`    | no       | The URL to the merge request that introduced the event.                                                                                                          |
+| `distributions`        | yes      | The [distributions](https://about.gitlab.com/handbook/marketing/strategic-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://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. Can be set to one or more of `free`, `premium`, or `ultimate`. |
+
+### Example event definition
+
+The linked [`uuid`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/events/epics_promote.yml)
+YAML file includes an example event definition.
+
+```yaml
+description: Issue promoted to epic
+category: epics
+action: promote
+property_description: The string "issue_id"
+value_description: ID of the issue
+extra_properties:
+  weight:
+    type: integer
+    description: Weight of the issue
+identifiers:
+- project
+- user
+- namespace
+product_section: dev
+product_stage: plan
+product_group: group::product planning
+product_category: epics
+milestone: "11.10"
+introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/10537
+distributions:
+- ee
+tiers:
+- premium
+- ultimate
+```
+
+## Create a new event definition
+
+Use the dedicated [event definition generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/snowplow_event_definition_generator.rb)
+to create new event definitions.
+
+The `category` and `action` of each event are included in the filename to enforce uniqueness.
+
+The generator takes three options:
+
+- `--ee`: Indicates if the event is for EE.
+- `--category=CATEGORY`: Indicates the `category` of the event.
+- `--action=ACTION`: Indicates the `action` of the event.
+- `--force`: Overwrites the existing event definition, if one already exists.
+
+```shell
+bundle exec rails generate gitlab:snowplow_event_definition --category Groups::EmailCampaignsController --action click
+create  create  config/events/groups__email_campaigns_controller_click.yml
+```
diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md
index c07291d61f2..ece72dbbf03 100644
--- a/doc/development/snowplow/index.md
+++ b/doc/development/snowplow/index.md
@@ -114,13 +114,13 @@ The current method provides several attributes that are sent on each click event
 
 | category* | label            | action                | property** | value |
 |-------------|------------------|-----------------------|----------|:-----:|
-| [root:index] | main_navigation            | click_navigation_link | `[link_label]`   | - |
-| [groups:boards:show] | toggle_swimlanes | click_toggle_button | - | `[is_active]` |
-| [projects:registry:index] | registry_delete | click_button | - | - |
-| [projects:registry:index] | registry_delete | confirm_deletion | - | - |
-| [projects:blob:show] | congratulate_first_pipeline | click_button | `[human_access]` | - |
-| [projects:clusters:new] | chart_options | generate_link | `[chart_link]` | - |
-| [projects:clusters:new] | chart_options | click_add_label_button | `[label_id]` | - |
+| `[root:index]` | `main_navigation`            | `click_navigation_link` | `[link_label]`   | - |
+| `[groups:boards:show]` | `toggle_swimlanes` | `click_toggle_button` | - | `[is_active]` |
+| `[projects:registry:index]` | `registry_delete` | `click_button` | - | - |
+| `[projects:registry:index]` | `registry_delete` | `confirm_deletion` | - | - |
+| `[projects:blob:show]` | `congratulate_first_pipeline` | `click_button` | `[human_access]` | - |
+| `[projects:clusters:new]` | `chart_options` | `generate_link` | `[chart_link]` | - |
+| `[projects:clusters:new]` | `chart_options` | `click_add_label_button` | `[label_id]` | - |
 
 _* It's ok to omit the category, and use the default._<br>
 _** Property is usually the best place for variable strings._
@@ -131,8 +131,8 @@ _** Property is usually the best place for variable strings._
 
 ```sql
 SELECT
+  session_id,
   event_id,
-  v_tracker,
   event_label,
   event_action,
   event_property,
@@ -427,7 +427,7 @@ https://docs.gitlab.com/ee/development/testing_guide/best_practices.html#test-sn
 
 ### Performance
 
-We use the [AsyncEmitter](https://github.com/snowplow/snowplow/wiki/Ruby-Tracker#52-the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development.
+We use the [AsyncEmitter](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/emitters/#the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development.
 
 ## Developing and testing Snowplow
 
@@ -579,6 +579,7 @@ The [`StandardContext`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/g
 | `namespace_id` | **{dotted-circle}** | integer               |                                                               |
 | `environment`  | **{check-circle}**  | string (max 32 chars) | Name of the source environment, such as `production` or `staging`             |
 | `source`       | **{check-circle}**  | string (max 32 chars) | Name of the source application, such as  `gitlab-rails` or `gitlab-javascript` |
+| `plan`         | **{dotted-circle}**  | string (max 32 chars) | Name of the plan for the namespace, such as `free`, `premium`, or `ultimate`. Automatically picked from the `namespace`. |
 | `extra`        | **{dotted-circle}**  | JSON                  | Any additional data associated with the event, in the form of key-value pairs |
 
 ### Default Schema