Merge branch 'jeromezng-master-patch-55538' into 'master'

Combine frontend and backend docs into snowplow doc

See merge request gitlab-org/gitlab!28630

doc/development/README.md

@@ -190,8 +190,7 @@ Complementary reads:
 ## Telemetry guides
 
 - [Introduction](../telemetry/index.md)
-- [Frontend tracking guide](../telemetry/frontend.md)
-- [Backend tracking guide](../telemetry/backend.md)
+- [Snowplow tracking guide](../telemetry/snowplow.md)
 
 ## Experiment Guide
 

doc/development/event_tracking/backend.md

 ---
-redirect_to: '../../telemetry/backend.md'
+redirect_to: '../../telemetry/index.md'
 ---
 
-This document was moved to [another location](../../telemetry/backend.md).
+This document was moved to [another location](../../telemetry/index.md).

doc/development/event_tracking/frontend.md

 ---
-redirect_to: '../../telemetry/frontend.md'
+redirect_to: '../../telemetry/index.md'
 ---
 
-This document was moved to [another location](../../telemetry/frontend.md).
+This document was moved to [another location](../../telemetry/index.md).

doc/telemetry/backend.md

-# Backend tracking guide
-
-GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby Tracker](https://github.com/snowplow/snowplow/wiki/ruby-tracker) for tracking custom events.
-
-## Tracking in Ruby
-
-Custom event tracking and instrumentation can be added by directly calling the `GitLab::Tracking.event` class method, which accepts the following arguments:
-
-| argument   | type   | default value              | description |
-|:-----------|:-------|:---------------------------|:------------|
-| `category` | string | 'application'              | Area or aspect of the application. This could be `HealthCheckController` or `Lfs::FileTransformer` for instance. |
-| `action`   | string | 'generic'                  | The action being taken, which can be anything from a controller action like `create` to something like an Active Record callback. |
-| `data`     | object | {}                         | Additional data such as `label`, `property`, `value`, and `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). These will be set as empty strings if you don't provide them. |
-
-Tracking can be viewed as either tracking user behavior, or can be utilized for instrumentation to monitor and visual performance over time in an area or aspect of code.
-
-For example:
-
-```ruby
-class Projects::CreateService < BaseService
-  def execute
-    project = Project.create(params)
-
-    Gitlab::Tracking.event('Projects::CreateService', 'create_project',
-      label: project.errors.full_messages.to_sentence,
-      value: project.valid?
-    )
-  end
-end
-```
-
-### 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.

doc/telemetry/index.md

@@ -36,14 +36,10 @@ Generally speaking, the frontend can track user actions and events, like:
 - Submitting forms.
 - Other typically interface-driven actions.
 
-See [Frontend tracking guide](frontend.md).
-
 ### Backend
 
 From the backend, the events that are tracked will likely consist of things like the creation or deletion of records and other events that might be triggered from layers that aren't necessarily only available in the interface.
 
-See [Backend tracking guide](backend.md).
-
 Also, see [Instrumenting Ruby code](../development/instrumentation.md) if you are instrumenting application performance metrics for Ruby code.
 
 ## Enabling tracking

doc/telemetry/frontend.md → doc/telemetry/snowplow.md

-# Frontend tracking guide
+# Snowplow tracking guide
+
+## Frontend tracking
 
 GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. There are a few ways to utilize tracking, but each generally requires at minimum, a `category` and an `action`. Additional data can be provided that adheres to our [Feature instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy).
 
@@ -8,7 +10,7 @@ GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tra
 | `action`   | string | 'generic'                  | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. |
 | `data`     | object | {}                         | Additional data such as `label`, `property`, `value`, and `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
 
-## Tracking in HAML (or Vue Templates)
+### Tracking in HAML (or Vue Templates)
 
 When working within HAML (or Vue templates) we can add `data-track-*` attributes to elements of interest. All elements that have a `data-track-event` attribute will automatically have event tracking bound on clicks.
 
@@ -38,7 +40,7 @@ Below is a list of supported `data-track-*` attributes:
 | `data-track-value`    | false    | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). If omitted, this will be the elements `value` property or an empty string. For checkboxes, the default value will be the element's checked attribute or `false` when unchecked. |
 | `data-track-context`  | false    | The `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
 
-## Tracking within Vue components
+### Tracking within Vue components
 
 There's a tracking Vue mixin that can be used in components if more complex tracking is required. To use it, first import the `Tracking` library and request a mixin.
 
@@ -99,7 +101,7 @@ And if needed within the template, you can use the `track` method directly as we
 </template>
 ```
 
-## Tracking in raw JavaScript
+### Tracking in raw JavaScript
 
 Custom event tracking and instrumentation can be added by directly calling the `Tracking.event` static function. The following example demonstrates tracking a click on a button by calling `Tracking.event` manually.
 
@@ -116,7 +118,7 @@ button.addEventListener('click', () => {
 })
 ```
 
-## Tests and test helpers
+### Tests and test helpers
 
 In Jest particularly in vue tests, you can use the following:
 
@@ -165,3 +167,38 @@ describe('my component', () => {
   });
 });
 ```
+
+## Backend tracking
+
+GitLab provides `Gitlab::Tracking`, an interface that wraps the [Snowplow Ruby Tracker](https://github.com/snowplow/snowplow/wiki/ruby-tracker) for tracking custom events.
+
+### Tracking in Ruby
+
+Custom event tracking and instrumentation can be added by directly calling the `GitLab::Tracking.event` class method, which accepts the following arguments:
+
+| argument   | type   | default value              | description |
+|:-----------|:-------|:---------------------------|:------------|
+| `category` | string | 'application'              | Area or aspect of the application. This could be `HealthCheckController` or `Lfs::FileTransformer` for instance. |
+| `action`   | string | 'generic'                  | The action being taken, which can be anything from a controller action like `create` to something like an Active Record callback. |
+| `data`     | object | {}                         | Additional data such as `label`, `property`, `value`, and `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). These will be set as empty strings if you don't provide them. |
+
+Tracking can be viewed as either tracking user behavior, or can be utilized for instrumentation to monitor and visual performance over time in an area or aspect of code.
+
+For example:
+
+```ruby
+class Projects::CreateService < BaseService
+  def execute
+    project = Project.create(params)
+
+    Gitlab::Tracking.event('Projects::CreateService', 'create_project',
+      label: project.errors.full_messages.to_sentence,
+      value: project.valid?
+    )
+  end
+end
+```
+
+### 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.