diff options
Diffstat (limited to 'doc/development/internal_analytics/internal_event_tracking')
5 files changed, 165 insertions, 0 deletions
diff --git a/doc/development/internal_analytics/internal_event_tracking/architecture.md b/doc/development/internal_analytics/internal_event_tracking/architecture.md new file mode 100644 index 00000000000..de5672a4895 --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/architecture.md @@ -0,0 +1,11 @@ +--- +stage: Analytics +group: Analytics Instrumentation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Internal event tracking architecture + +This page is under construction. It serves as placeholder for the following information. + +- Detailed architecture and other technical details diff --git a/doc/development/internal_analytics/internal_event_tracking/event_definition_guide.md b/doc/development/internal_analytics/internal_event_tracking/event_definition_guide.md new file mode 100644 index 00000000000..7e4222ead2e --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/event_definition_guide.md @@ -0,0 +1,11 @@ +--- +stage: Analytics +group: Analytics Instrumentation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Internal event tracking definition guide + +This page is under construction. It serves as placeholder for the following information. + +- Explanation of all parts of an event definition diff --git a/doc/development/internal_analytics/internal_event_tracking/index.md b/doc/development/internal_analytics/internal_event_tracking/index.md new file mode 100644 index 00000000000..73e9e2d1a4c --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/index.md @@ -0,0 +1,17 @@ +--- +stage: Analytics +group: Analytics Instrumentation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Internal Event Tracking + +This page provides detailed guidelines on using the Internal Event Tracking system to instrument features on GitLab. + +This page is a work in progress. For any questions or clarifications, reach out to us in the Slack channel [#g_analyze_analytics_instrumentation](https://gitlab.slack.com/archives/CL3A7GFPF). + +- [Introduction to internal event tracking](introduction.md#internal-event-tracking) +- [Quick start guide](quick_start.md#quick-start-for-internal-event-tracking) +- [Event definition guide](event_definition_guide.md#internal-event-tracking-definition-guide) +- [Metrics dictionary guide](../service_ping/metrics_dictionary.md#metrics-dictionary-guide) +- [Architecture](architecture.md#internal-event-tracking-architecture) diff --git a/doc/development/internal_analytics/internal_event_tracking/introduction.md b/doc/development/internal_analytics/internal_event_tracking/introduction.md new file mode 100644 index 00000000000..ebb3caa198a --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/introduction.md @@ -0,0 +1,13 @@ +--- +stage: Analytics +group: Analytics Instrumentation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Internal event tracking + +This page is under construction. It serves as placeholder for the following information: + +- High level introduction +- Difference between Events and Metrics +- Basic overview of the architecture diff --git a/doc/development/internal_analytics/internal_event_tracking/quick_start.md b/doc/development/internal_analytics/internal_event_tracking/quick_start.md new file mode 100644 index 00000000000..84926657a3b --- /dev/null +++ b/doc/development/internal_analytics/internal_event_tracking/quick_start.md @@ -0,0 +1,113 @@ +--- +stage: Analytics +group: Analytics Instrumentation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Quick start for internal event tracking + +In an effort to provide a more efficient, scalable, and unified tracking API, GitLab is deprecating existing RedisHLL and Snowplow tracking. Instead, we're implementing a new `track_event` method. +With this approach, we can both update RedisHLL counters and send Snowplow events simultaneously, streamlining the tracking process. + +## Create and trigger events + +### Backend tracking + +To trigger an event, call the `Gitlab::InternalEvents.track_event` method with the desired arguments: + +```ruby +Gitlab::InternalEvents.track_event( + "i_code_review_user_apply_suggestion", + user_id: user_id, + namespace_id: namespace_id, + project_id: project_id + ) +``` + +This method automatically increments all RedisHLL metrics relating to the event `i_code_review_user_apply_suggestion`, and sends a corresponding Snowplow event with all named arguments and standard context (SaaS only). + +### Frontend tracking + +#### Vue components + +In Vue components, tracking can be done with [Vue mixin](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/internal_events.js#L29). + +To implement Vue component tracking: + +1. Import the `InternalEvents` library and call the `mixin` method: + + ```javascript + import { InternalEvents } from '~/tracking'; + const trackingMixin = InternalEvents.mixin(); + ``` + +1. Use the mixin in the component: + + ```javascript + export default { + mixins: [trackingMixin], + + data() { + return { + expanded: false, + }; + }, + }; + ``` + +1. Call the `track_event` method. Tracking options can be passed as the second parameter: + + ```javascript + this.track_event('i_code_review_user_apply_suggestion'); + ``` + + Or use the `track_event` method in the template: + + ```html + <template> + <div> + <button data-testid="toggle" @click="toggle">Toggle</button> + + <div v-if="expanded"> + <p>Hello world!</p> + <button @click="track_event('i_code_review_user_apply_suggestion')">Track another event</button> + </div> + </div> + </template> + ``` + +#### Raw JavaScript + +For tracking events directly from arbitrary frontend JavaScript code, a module for raw JavaScript is provided. This can be used outside of a component context where the Mixin cannot be utilized. + +```javascript +import { InternalEvents } from '~/tracking'; +InternalEvents.track_event('i_code_review_user_apply_suggestion'); +``` + +#### Data-track attribute + +This attribute ensures that if we want to track GitLab internal events for a button, we do not need to write JavaScript code on Click handler. Instead, we can just add a data-event-tracking attribute with event value and it should work. This can also be used with haml views. + +```html + <gl-button + data-event-tracking="i_analytics_dev_ops_adoption" + > + Click Me + </gl-button> +``` + +For Haml + +```haml += render Pajamas::ButtonComponent.new(button_options: { class: 'js-settings-toggle', data: { event_tracking: 'action' }}) do +``` + +#### Internal events on render + +Sometimes we want to send internal events when the component is rendered or loaded. In these cases, we can add the `data-event-tracking-load="true"` attribute: + +```haml += render Pajamas::ButtonComponent.new(button_options: { data: { event_tracking_load: 'true', event_tracking: 'i_devops' } }) do + = _("New project") +``` |