diff options
Diffstat (limited to 'doc/development/snowplow')
-rw-r--r-- | doc/development/snowplow/dictionary.md | 44 | ||||
-rw-r--r-- | doc/development/snowplow/event_dictionary_guide.md | 94 | ||||
-rw-r--r-- | doc/development/snowplow/index.md | 19 |
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 |