diff options
Diffstat (limited to 'doc/development/internal_analytics')
13 files changed, 193 insertions, 251 deletions
diff --git a/doc/development/internal_analytics/index.md b/doc/development/internal_analytics/index.md index 8abea4c2b2f..c7cf907ca92 100644 --- a/doc/development/internal_analytics/index.md +++ b/doc/development/internal_analytics/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Internal analytics -Learn how to implement internal analytics using: +Learn how to instrument your features on GitLab using: - [Service Ping](service_ping/index.md) - [Snowplow](snowplow/index.md) 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") +``` diff --git a/doc/development/internal_analytics/internal_events/index.md b/doc/development/internal_analytics/internal_events/index.md index cbc7b73a282..d987317a2b0 100644 --- a/doc/development/internal_analytics/internal_events/index.md +++ b/doc/development/internal_analytics/internal_events/index.md @@ -1,98 +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 +redirect_to: '../internal_event_tracking/quick_start.md' +remove_date: '2023-10-27' --- -# Internal Events development guidelines +This document was moved to [another location](../internal_event_tracking/quick_start.md). -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> -``` +<!-- This redirect file can be deleted after <2023-10-27>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/internal_analytics/service_ping/implement.md b/doc/development/internal_analytics/service_ping/implement.md index 3b8243377a3..9dbfa02854d 100644 --- a/doc/development/internal_analytics/service_ping/implement.md +++ b/doc/development/internal_analytics/service_ping/implement.md @@ -21,7 +21,6 @@ To implement a new metric in Service Ping, follow these steps: 1. [Generate the SQL query](#generate-the-sql-query) 1. [Optimize queries with Database Lab](#optimize-queries-with-database-lab) 1. [Add the metric definition to the Metrics Dictionary](#add-the-metric-definition) -1. [Add the metric to the Versions Application](#add-the-metric-to-the-versions-application) 1. [Create a merge request](#create-a-merge-request) 1. [Verify your metric](#verify-your-metric) 1. [Set up and test Service Ping locally](#set-up-and-test-service-ping-locally) @@ -324,25 +323,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd/) and [P ##### Add new events -1. Define events in [`known_events`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/). - - Example event: - - ```yaml - - name: users_creating_epics - aggregation: weekly - ``` - - Keys: - - - `name`: unique event name. - - Name format for Redis HLL events `{hll_counters}_<name>` - - Example names: `users_creating_epics`, `users_triggering_security_scans`. - - - `aggregation`: may be set to a `:daily` or `:weekly` key. Defines how counting data is stored in Redis. - Aggregation on a `daily` basis does not pull more fine grained data. +1. Add an event to the required metric ([see example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20230210200054_i_ee_code_review_merge_request_widget_license_compliance_expand_weekly.yml#L17-17)) or create a metric. 1. Use one of the following methods to track the event: @@ -447,7 +428,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd/) and [P - Using the JavaScript/Vue API helper, which calls the [`UsageData` API](#usagedata-api). - Example for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/): + Example for an existing event already defined in [metric fields](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20220407125907_p_ci_templates_themekit_monthly.yml#L17-17): ```javascript import api from '~/api'; @@ -485,7 +466,6 @@ Next, get the unique events for the current week. We have the following recommendations for [adding new events](#add-new-events): -- Event aggregation: weekly. - When adding new metrics, use a [feature flag](../../../operations/feature_flags.md) to control the impact. It's recommended to disable the new feature flag by default (set `default_enabled: false`). - Events can be triggered using the `UsageData` API, which helps when there are > 10 events per change @@ -501,7 +481,7 @@ We can disable tracking completely by using the global flag: ##### Known events are added automatically in Service Data payload -Service Ping adds all events [`known_events/*.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events) to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/db/schema.rb#L213). +Service Ping adds all events to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/db/schema.rb#L213). For each event we add metrics for the weekly and monthly time frames, and totals for each where applicable: - `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#add-new-events) events and data for the last complete week for weekly [aggregation](#add-new-events) events. @@ -540,8 +520,6 @@ Example: # Redis Counters redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter) -# Define events in common.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml - # Tracking events Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_expanding_vulnerabilities', values: visitor_id) @@ -678,10 +656,6 @@ For more details, see the [database review guide](../../database_review.md#prepa See the [Metrics Dictionary guide](metrics_dictionary.md) for more information. -## Add the metric to the Versions Application - -Check if the new metric must be added to the Versions Application. See the `usage_data` [schema](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/db/schema.rb#L152) and Service Data [parameters accepted](https://gitlab.com/gitlab-org/gitlab-services/version.gitlab.com/-/blob/main/app/services/usage_ping.rb). Any metrics added under the `counts` key are saved in the `stats` column. - ## Create a merge request Create a merge request for the new Service Ping metric, and do the following: @@ -809,13 +783,7 @@ create metric YAML definition file following [Aggregated metric instrumentation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45979) in GitLab 13.6. -To declare the aggregate of events collected with [Redis HLL Counters](#redis-hll-counters), -you must fulfill the following requirements: - -1. All events listed at `events` attribute must come from - [`known_events/*.yml`](#known-events-are-added-automatically-in-service-data-payload) files. -1. All events listed at `events` attribute must have the same `aggregation` attribute. -1. `time_frame` does not include `all` value, which is unavailable for Redis sourced aggregated metrics. +To declare the aggregate of events collected with [Redis HLL Counters](#redis-hll-counters), make sure `time_frame` does not include the `all` value, which is unavailable for Redis-sourced aggregated metrics. While it is possible to aggregate EE-only events together with events that occur in all GitLab editions, it's important to remember that doing so may produce high variance between data collected from EE and CE GitLab instances. diff --git a/doc/development/internal_analytics/service_ping/metrics_dictionary.md b/doc/development/internal_analytics/service_ping/metrics_dictionary.md index f56955ed422..8103db5113f 100644 --- a/doc/development/internal_analytics/service_ping/metrics_dictionary.md +++ b/doc/development/internal_analytics/service_ping/metrics_dictionary.md @@ -32,7 +32,6 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | Field | Required | Additional information | |---------------------|----------|----------------------------------------------------------------| | `key_path` | yes | JSON key path for the metric, location in Service Ping payload. | -| `name` (deprecated) | no | Metric name suggestion. Does not have any impact on the Service Ping payload, only serves as documentation. | | `description` | yes | | | `product_section` | yes | The [section](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/sections.yml). | | `product_stage` | yes | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. | @@ -71,42 +70,6 @@ NOTE: We can't control what the metric's `key_path` is, because some of them are generated dynamically in `usage_data.rb`. For example, see [Redis HLL metrics](implement.md#redis-hll-counters). -### Metric name (deprecated) - -WARNING: -This feature was deprecated in GitLab 16.1 -and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/411602) in 16.2. - -To improve metric discoverability by a wider audience, each metric with -instrumentation added at an appointed `key_path` receives a `name` attribute -filled with the name suggestion, corresponding to the metric `data_source` and instrumentation. -Metric name suggestions can contain two types of elements: - -1. **User input prompts**: enclosed by angle brackets (`< >`), these pieces should be replaced or - removed when you create a metrics YAML file. -1. **Fixed suggestion**: plaintext parts generated according to well-defined algorithms. - They are based on underlying instrumentation, and must not be changed. - -For a metric name to be valid, it must not include any prompt, and fixed suggestions -must not be changed. - -#### Generate a metric name suggestion (deprecated) - -WARNING: -This feature was deprecated in GitLab 16.1 -and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/411602) in 16.2. - -The metric YAML generator can suggest a metric name for you. -To generate a metric name suggestion, first instrument the metric at the provided `key_path`. -Then, generate the metric's YAML definition and -return to the instrumentation and update it. - -1. Add the metric instrumentation class to `lib/gitlab/usage/metrics/instrumentations/`. -1. Add the metric logic in the instrumentation class. -1. Run the [metrics YAML generator](metrics_dictionary.md#create-a-new-metric-definition). -1. Use the metric name suggestion to select a suitable metric name. -1. Update the metric's YAML definition with the correct `key_path`. - ### Metric statuses Metric definitions can have one of the following statuses: @@ -130,20 +93,16 @@ which has a related schema in `/config/metrics/objects_schemas/topology_schema.j ### Metric `time_frame` A metric's time frame is calculated based on the `time_frame` field and the `data_source` of the metric. -For `redis_hll` metrics, the type of aggregation is also taken into consideration. In this context, the term "aggregation" refers to [chosen events data storage interval](implement.md#add-new-events), and is **NOT** related to the Aggregated Metrics feature. -For more information about the aggregation type of each feature, see the [`common.yml` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml). Weeks run from Monday to Sunday. - -| data_source | time_frame | aggregation | Description | -|------------------------|------------|----------------|-------------------------------------------------| -| any | `none` | not applicable | A type of data that's not tracked over time, such as settings and configuration information | -| `database` | `all` | not applicable | The whole time the metric has been active (all-time interval) | -| `database` | `7d` | not applicable | 9 days ago to 2 days ago | -| `database` | `28d` | not applicable | 30 days ago to 2 days ago | -| `redis` | `all` | not applicable | The whole time the metric has been active (all-time interval) | -| `redis_hll` | `7d` | `daily` | Most recent 7 complete days | -| `redis_hll` | `7d` | `weekly` | Most recent complete week | -| `redis_hll` | `28d` | `daily` | Most recent 28 complete days | -| `redis_hll` | `28d` | `weekly` | Most recent 4 complete weeks | + +| data_source | time_frame | Description | +|------------------------|------------|-------------------------------------------------| +| any | `none` | A type of data that's not tracked over time, such as settings and configuration information | +| `database` | `all` | The whole time the metric has been active (all-time interval) | +| `database` | `7d` | 9 days ago to 2 days ago | +| `database` | `28d` | 30 days ago to 2 days ago | +| `redis` | `all` | The whole time the metric has been active (all-time interval) | +| `redis_hll` | `7d` | Most recent complete week | +| `redis_hll` | `28d` | Most recent 4 complete weeks | ### Data category @@ -157,69 +116,6 @@ We use the following categories to classify a metric: An aggregate metric is a metric that is the sum of two or more child metrics. Service Ping uses the data category of the aggregate metric to determine whether or not the data is included in the reported Service Ping payload. -### Metric name suggestion examples (deprecated) - -WARNING: -This feature was deprecated in GitLab 16.1 -and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/411602) in 16.2. - -#### Metric with `data_source: database` - -For a metric instrumented with SQL: - -```sql -SELECT COUNT(DISTINCT user_id) FROM clusters WHERE clusters.management_project_id IS NOT NULL -``` - -- **Suggested name**: `count_distinct_user_id_from_<adjective describing: '(clusters.management_project_id IS NOT NULL)'>_clusters` -- **Prompt**: `<adjective describing: '(clusters.management_project_id IS NOT NULL)'>` - should be replaced with an adjective that best represents filter conditions, such as `project_management` -- **Final metric name**: For example, `count_distinct_user_id_from_project_management_clusters` - -For metric instrumented with SQL: - -```sql -SELECT COUNT(DISTINCT clusters.user_id) -FROM clusters_applications_helm -INNER JOIN clusters ON clusters.id = clusters_applications_helm.cluster_id -WHERE clusters_applications_helm.status IN (3, 5) -``` - -- **Suggested name**: `count_distinct_user_id_from_<adjective describing: '(clusters_applications_helm.status IN (3, 5))'>_clusters_<with>_<adjective describing: '(clusters_applications_helm.status IN (3, 5))'>_clusters_applications_helm` -- **Prompt**: `<adjective describing: '(clusters_applications_helm.status IN (3, 5))'>` - should be replaced with an adjective that best represents filter conditions -- **Final metric name**: `count_distinct_user_id_from_clusters_with_available_clusters_applications_helm` - -In the previous example, the prompt is irrelevant, and user can remove it. The second -occurrence corresponds with the `available` scope defined in `Clusters::Concerns::ApplicationStatus`. -It can be used as the right adjective to replace prompt. - -The `<with>` represents a suggested conjunction for the suggested name of the joined relation. -The person documenting the metric can use it by either: - -- Removing the surrounding `<>`. -- Using a different conjunction, such as `having` or `including`. - -#### Metric with `data_source: redis` or `redis_hll` - -For metrics instrumented with a Redis-based counter, the suggested name includes -only the single prompt to be replaced by the person working with metrics YAML. - -- **Prompt**: `<please fill metric name, suggested format is: {subject}_{verb}{ing|ed}_{object} eg: users_creating_epics or merge_requests_viewed_in_single_file_mode>` -- **Final metric name**: We suggest the metric name should follow the format of - `{subject}_{verb}{ing|ed}_{object}`, such as `user_creating_epics`, `users_triggering_security_scans`, - or `merge_requests_viewed_in_single_file_mode` - -#### Metric with `data_source: prometheus` or `system` - -For metrics instrumented with Prometheus or coming from the operating system, -the suggested name includes only the single prompt by person working with metrics YAML. - -- **Prompt**: `<please fill metric name>` -- **Final metric name**: Due to the variety of cases that can apply to this kind of metric, - no naming convention exists. Each person instrumenting a metric should use their - best judgment to come up with a descriptive name. - ### Example YAML metric definition The linked [`uuid`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/uuid.yml) diff --git a/doc/development/internal_analytics/service_ping/metrics_lifecycle.md b/doc/development/internal_analytics/service_ping/metrics_lifecycle.md index 7aa0eaa1554..bb3d6797011 100644 --- a/doc/development/internal_analytics/service_ping/metrics_lifecycle.md +++ b/doc/development/internal_analytics/service_ping/metrics_lifecycle.md @@ -103,4 +103,3 @@ To remove a metric: 1. Remove any other records related to the metric: - The feature flag YAML file at [`config/feature_flags/*/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/feature_flags). - - The entry in the known events YAML file at [`lib/gitlab/usage_data_counters/known_events/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/usage_data_counters/known_events). diff --git a/doc/development/internal_analytics/service_ping/review_guidelines.md b/doc/development/internal_analytics/service_ping/review_guidelines.md index 31b6c3f5580..8a46de7086e 100644 --- a/doc/development/internal_analytics/service_ping/review_guidelines.md +++ b/doc/development/internal_analytics/service_ping/review_guidelines.md @@ -51,7 +51,7 @@ are regular backend changes. #### The Analytics Instrumentation **reviewer** should - Perform a first-pass review on the merge request and suggest improvements to the author. -- Check the [metrics location](metrics_dictionary.md#metric-key_path) in +- Check the [metric's location](metrics_dictionary.md#metric-key_path) in the Service Ping JSON payload. - Add the `~database` label and ask for a [database review](../../database_review.md) for metrics that are based on Database. @@ -66,6 +66,7 @@ are regular backend changes. - Check the file location. Consider the time frame, and if the file should be under `ee`. - Check the tiers. - If a metric was changed or removed: Make sure the MR author notified the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) by `@` mentioning those groups in a comment on the issue for the MR and all of these groups have acknowledged the removal. +- Make sure that the new metric is available in Service Ping payload, by running: `Gitlab::Usage::ServicePingReport.for(output: :all_metrics_values).dig(*'key_path'.split('.'))` with `key_path` substituted by the new metric's key_path. - Metrics instrumentations - Recommend using metrics instrumentation for new metrics, [if possible](metrics_instrumentation.md#support-for-instrumentation-classes). - Approve the MR, and relabel the MR with `~"analytics instrumentation::approved"`. diff --git a/doc/development/internal_analytics/service_ping/troubleshooting.md b/doc/development/internal_analytics/service_ping/troubleshooting.md index 7f7b4099d48..8f5e94506cd 100644 --- a/doc/development/internal_analytics/service_ping/troubleshooting.md +++ b/doc/development/internal_analytics/service_ping/troubleshooting.md @@ -76,7 +76,7 @@ checking the configuration file of your GitLab instance: - `/etc/gitlab/gitlab.rb` for Linux package installations and Docker. - `charts.yaml` for GitLab Helm and cloud-native Kubernetes deployments. - - `gitlab.yml` for GitLab installations from source. + - `gitlab.yml` for self-compiled installations. To check the relevant configuration file for strings that indicate whether Service Ping is disabled, you can use `grep`: diff --git a/doc/development/internal_analytics/snowplow/troubleshooting.md b/doc/development/internal_analytics/snowplow/troubleshooting.md index 2f59543e0f4..b531c6dcd56 100644 --- a/doc/development/internal_analytics/snowplow/troubleshooting.md +++ b/doc/development/internal_analytics/snowplow/troubleshooting.md @@ -21,8 +21,8 @@ You will be alarmed via a [Sisense alert](https://app.periscopedata.com/app/gitl ### Locating the problem First you need to identify at which stage in Snowplow the data pipeline the drop is occurring. -Start at [Snowplow dashboard](https://console.aws.amazon.com/systems-manager/resource-groups/cloudwatch?dashboard=SnowPlow®ion=us-east-1#) on CloudWatch, -if you do not have access to CloudWatch you need to create an [access request issue](https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/9730) first. +Start at [Snowplow dashboard](https://console.aws.amazon.com/systems-manager/resource-groups/cloudwatch?dashboard=SnowPlow®ion=us-east-1#) on CloudWatch. +If you do not have access to CloudWatch, GitLab team members can create an access request issue, similar to this one: `https://gitlab.com/gitlab-com/team-member-epics/access-requests/-/issues/9730`. While on CloudWatch dashboard set time range to last 4 weeks, to get better picture of system characteristics over time. Than visit following charts: 1. `ELB New Flow Count` and `Collector Auto Scaling Group Network In/Out` - they show in order: number of connections to collectors via load balancers and data volume (in bytes) processed by collectors. If there is drop visible there, it means less events were fired from the GitLab application. Proceed to [application layer guide](#troubleshooting-gitlab-application-layer) for more details @@ -42,7 +42,7 @@ or even a result of a public holiday in some regions of the world with a larger 1. Check (via [Grafana explore tab](https://dashboards.gitlab.net/explore) ) following Prometheus counters `gitlab_snowplow_events_total`, `gitlab_snowplow_failed_events_total` and `gitlab_snowplow_successful_events_total` to see how many events were fired correctly from GitLab.com. Example query to use `sum(rate(gitlab_snowplow_successful_events_total{env="gprd"}[5m])) / sum(rate(gitlab_snowplow_events_total{env="gprd"}[5m]))` would chart rate at which number of good events rose in comparison to events sent in total. If number drops from 1 it means that problem might be in communication between GitLab and AWS collectors fleet. 1. Check [logs in Kibana](https://log.gprd.gitlab.net/app/discover#) and filter with `{ "query": { "match_phrase": { "json.message": "failed to be reported to collector at" } } }` if there are some failed events logged -We conducted an investigation into an unexpected drop in snowplow events volume. +We conducted an investigation into an unexpected drop in snowplow events volume. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/335206` |