Add latest changes from gitlab-org/gitlab@15-1-stable-eev15.1.0-rc42

4 files changed, 112 insertions, 26 deletions

diff --git a/doc/development/service_ping/implement.md b/doc/development/service_ping/implement.md
index 27bc4d2e8ca..6948eb20e00 100644
--- a/doc/development/service_ping/implement.md
+++ b/doc/development/service_ping/implement.md
@@ -46,7 +46,7 @@ boards: add_metric('CountBoardsMetric', time_frame: 'all'),
 
 There are several types of counters for metrics:
 
-- **[Batch counters](#batch-counters)**: Used for counts and sums.
+- **[Batch counters](#batch-counters)**: Used for counts, sums, and averages.
 - **[Redis counters](#redis-counters):** Used for in-memory counts.
 - **[Alternative counters](#alternative-counters):** Used for settings and configurations.
 
@@ -102,34 +102,32 @@ Examples using `usage_data.rb` have been [deprecated](usage_data.md). We recomme
 
 #### Sum batch operation
 
-There is no support for `sum` for database metrics.
-
 Sum the values of a given ActiveRecord_Relation on given column and handles errors.
 Handles the `ActiveRecord::StatementInvalid` error
 
 Method:
 
 ```ruby
-sum(relation, column, batch_size: nil, start: nil, finish: nil)
+add_metric('JiraImportsTotalImportedIssuesCountMetric')
 ```
 
-Arguments:
+#### Average batch operation
 
-- `relation`: the ActiveRecord_Relation to perform the operation
-- `column`: the column to sum on
-- `batch_size`: if none set it uses default value 1000 from `Gitlab::Database::BatchCounter`
-- `start`: custom start of the batch counting to avoid complex min calculations
-- `end`: custom end of the batch counting to avoid complex min calculations
+Average the values of a given `ActiveRecord_Relation` on given column and handles errors.
 
-Examples:
+Method:
 
 ```ruby
-sum(JiraImportState.finished, :imported_issues_count)
+add_metric('CountIssuesWeightAverageMetric')
 ```
 
+Examples:
+
+Examples using `usage_data.rb` have been [deprecated](usage_data.md). We recommend to use [instrumentation classes](metrics_instrumentation.md).
+
 #### Grouping and batch operations
 
-The `count`, `distinct_count`, and `sum` batch counters can accept an `ActiveRecord::Relation`
+The `count`, `distinct_count`, `sum`, and `average` batch counters can accept an `ActiveRecord::Relation`
 object, which groups by a specified column. With a grouped relation, the methods do batch counting,
 handle errors, and returns a hash table of key-value pairs.
 
@@ -144,6 +142,9 @@ distinct_count(Project.group(:visibility_level), :creator_id)
 
 sum(Issue.group(:state_id), :weight))
 # returns => {1=>3542, 2=>6820}
+
+average(Issue.group(:state_id), :weight))
+# returns => {1=>3.5, 2=>2.5}
 ```
 
 #### Add operation
@@ -286,7 +287,7 @@ Enabled by default in GitLab 13.7 and later.
    Increment event count using an ordinary Redis counter, for a given event name.
 
    API requests are protected by checking for a valid CSRF token.
-   
+
    ```plaintext
    POST /usage_data/increment_counter
    ```
@@ -652,9 +653,10 @@ We return fallback values in these cases:
 
 | Case                        | Value |
 |-----------------------------|-------|
-| Deprecated Metric           | -1000 |
+| Deprecated Metric ([Removed with version 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/335894)) | -1000 |
 | Timeouts, general failures  | -1    |
 | Standard errors in counters | -2    |
+| Histogram metrics failure   | { '-1' => -1 } |
 
 ## Test counters manually using your Rails console
 
diff --git a/doc/development/service_ping/index.md b/doc/development/service_ping/index.md
index 1e09dada36e..e776b78b710 100644
--- a/doc/development/service_ping/index.md
+++ b/doc/development/service_ping/index.md
@@ -464,7 +464,7 @@ To generate Service Ping, use [Teleport](https://goteleport.com/docs/) or a deta
 
 1. Get the metrics duration from logs:
 
-Search in Google Console logs for `time_elapsed`. Query example [here](https://cloudlogging.app.goo.gl/nWheZvD8D3nWazNe6).
+Search in Google Console logs for `time_elapsed`. [Query example](https://cloudlogging.app.goo.gl/nWheZvD8D3nWazNe6).
 
 ### Verification (After approx 30 hours)
 
diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md
index ead11a412fa..fee3bb571c2 100644
--- a/doc/development/service_ping/metrics_dictionary.md
+++ b/doc/development/service_ping/metrics_dictionary.md
@@ -35,7 +35,7 @@ Each metric is defined in a separate YAML file consisting of a number of fields:
 | `name`              | no       | Metric name suggestion. Can replace the last part of `key_path`. |
 | `description`       | yes      |                                                                |
 | `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 metric. |
+| `product_stage`     | yes       | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. |
 | `product_group`     | yes      | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the metric. |
 | `product_category`  | no       | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the metric. |
 | `value_type`        | yes      | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html).                                                     |
@@ -43,11 +43,11 @@ Each metric is defined in a separate YAML file consisting of a number of fields:
 | `time_frame`        | yes      | `string`; may be set to a value like `7d`, `28d`, `all`, `none`. |
 | `data_source`       | yes      | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `system`. |
 | `data_category`     | yes      | `string`; [categories](#data-category) of the metric, may be set to `operational`, `optional`, `subscription`, `standard`. The default value is `optional`.|
-| `instrumentation_class` | no   | `string`; [the class that implements the metric](metrics_instrumentation.md).  |
+| `instrumentation_class` | yes   | `string`; [the class that implements the metric](metrics_instrumentation.md).  |
 | `distribution`      | yes      | `array`; may be set to one of `ce, ee` or `ee`. The [distribution](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/#definitions) where the tracked feature is available.  |
 | `performance_indicator_type`  | no      | `array`; may be set to one of [`gmau`, `smau`, `paid_gmau`, or `umau`](https://about.gitlab.com/handbook/business-technology/data-team/data-catalog/xmau-analysis/). |
 | `tier`              | yes      | `array`; may contain one or a combination of `free`, `premium` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. This should be verbose and contain all tiers where a metric is available. |
-| `milestone`         | no       | The milestone when the metric is introduced and when it's available to self-managed instances with the official GitLab release. |
+| `milestone`         | yes       | The milestone when the metric is introduced and when it's available to self-managed instances with the official GitLab release. |
 | `milestone_removed` | no       | The milestone when the metric is removed. |
 | `introduced_by_url` | no       | The URL to the merge request that introduced the metric to be available for self-managed instances. |
 | `removed_by_url`    | no       | The URL to the merge request that removed the metric. |
diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md
index e718d972fba..4fd03eea84f 100644
--- a/doc/development/service_ping/metrics_instrumentation.md
+++ b/doc/development/service_ping/metrics_instrumentation.md
@@ -8,10 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 This guide describes how to develop Service Ping metrics using metrics instrumentation.
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For a video tutorial, see the [Adding Service Ping metric via instrumentation class](https://youtu.be/p2ivXhNxUoY).
+
 ## Nomenclature
 
 - **Instrumentation class**:
-  - Inherits one of the metric classes: `DatabaseMetric`, `RedisMetric`, `RedisHLLMetric` or `GenericMetric`.
+  - Inherits one of the metric classes: `DatabaseMetric`, `RedisMetric`, `RedisHLLMetric`, `NumbersMetric` or `GenericMetric`.
   - Implements the logic that calculates the value for a Service Ping metric.
 
 - **Metric definition**
@@ -24,7 +27,7 @@ This guide describes how to develop Service Ping metrics using metrics instrumen
 
 A metric definition has the [`instrumentation_class`](metrics_dictionary.md) field, which can be set to a class.
 
-The defined instrumentation class should inherit one of the existing metric classes: `DatabaseMetric`, `RedisMetric`, `RedisHLLMetric`, or `GenericMetric`.
+The defined instrumentation class should inherit one of the existing metric classes: `DatabaseMetric`, `RedisMetric`, `RedisHLLMetric`, `NumbersMetric` or `GenericMetric`.
 
 The current convention is that a single instrumentation class corresponds to a single metric. On a rare occasions, there are exceptions to that convention like [Redis metrics](#redis-metrics). To use a single instrumentation class for more than one metric, please reach out to one of the `@gitlab-org/growth/product-intelligence/engineers` members to consult about your case.
 
@@ -35,7 +38,7 @@ We have built a domain-specific language (DSL) to define the metrics instrumenta
 
 ## Database metrics
 
-- `operation`: Operations for the given `relation`, one of `count`, `distinct_count`.
+- `operation`: Operations for the given `relation`, one of `count`, `distinct_count`, `sum`, and `average`.
 - `relation`: `ActiveRecord::Relation` for the objects we want to perform the `operation`.
 - `start`: Specifies the start value of the batch counting, by default is `relation.minimum(:id)`.
 - `finish`: Specifies the end value of the batch counting, by default is `relation.maximum(:id)`.
@@ -104,6 +107,46 @@ module Gitlab
 end
 ```
 
+### Sum Example
+
+```ruby
+# frozen_string_literal: true
+
+module Gitlab
+  module Usage
+    module Metrics
+      module Instrumentations
+        class JiraImportsTotalImportedIssuesCountMetric < DatabaseMetric
+          operation :sum, column: :imported_issues_count
+
+          relation { JiraImportState.finished }
+        end
+      end
+    end
+  end
+end
+```
+
+### Average Example
+
+```ruby
+# frozen_string_literal: true
+
+module Gitlab
+  module Usage
+    module Metrics
+      module Instrumentations
+        class CountIssuesWeightAverageMetric < DatabaseMetric
+          operation :average, column: :weight
+
+          relation { Issue }
+        end
+      end
+    end
+  end
+end
+```
+
 ## Redis metrics
 
 [Example of a merge request that adds a `Redis` metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66582).
@@ -201,6 +244,43 @@ options:
     - i_quickactions_approve
 ```
 
+## Numbers metrics
+
+- `operation`: Operations for the given `data` block. Currently we only support `add` operation.
+- `data`: a `block` which contains an array of numbers.
+- `available?`: Specifies whether the metric should be reported. The default is `true`.
+
+```ruby
+# frozen_string_literal: true
+
+module Gitlab
+  module Usage
+    module Metrics
+      module Instrumentations
+          class IssuesBoardsCountMetric < NumbersMetric
+            operation :add
+
+            data do |time_frame|
+              [
+                 CountIssuesMetric.new(time_frame: time_frame).value,
+                 CountBoardsMetric.new(time_frame: time_frame).value
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+You must also include the instrumentation class name in the YAML setup.
+
+```yaml
+time_frame: 28d
+instrumentation_class: 'IssuesBoardsCountMetric'
+```
+
 ## Generic metrics
 
 - `value`: Specifies the value of the metric.
@@ -228,14 +308,15 @@ end
 
 There is support for:
 
-- `count`, `distinct_count`, `estimate_batch_distinct_count` for [database metrics](#database-metrics).
+- `count`, `distinct_count`, `estimate_batch_distinct_count`, `sum`, and `average` for [database metrics](#database-metrics).
 - [Redis metrics](#redis-metrics).
 - [Redis HLL metrics](#redis-hyperloglog-metrics).
+- `add` for [numbers metrics](#numbers-metrics).
 - [Generic metrics](#generic-metrics), which are metrics based on settings or configurations.
 
 There is no support for:
 
-- `add`, `sum`, `histogram` for database metrics.
+- `add`, `histogram` for database metrics.
 
 You can [track the progress to support these](https://gitlab.com/groups/gitlab-org/-/epics/6118).
 
@@ -245,8 +326,10 @@ To create a stub instrumentation for a Service Ping metric, you can use a dedica
 
 The generator takes the class name as an argument and the following options:
 
-- `--type=TYPE` Required. Indicates the metric type. It must be one of: `database`, `generic`, `redis`.
-- `--operation` Required for `database` type. It must be one of: `count`, `distinct_count`, `estimate_batch_distinct_count`.
+- `--type=TYPE` Required. Indicates the metric type. It must be one of: `database`, `generic`, `redis`, `numbers`.
+- `--operation` Required for `database` & `numebers` type.
+  - For `database` it must be one of: `count`, `distinct_count`, `estimate_batch_distinct_count`, `sum`, `average`.
+  - For `numbers` it must be: `add`.
 - `--ee` Indicates if the metric is for EE.
 
 ```shell
@@ -264,6 +347,7 @@ This guide describes how to migrate a Service Ping metric from [`lib/gitlab/usag
 - [Database metric](#database-metrics)
 - [Redis HyperLogLog metrics](#redis-hyperloglog-metrics)
 - [Redis metric](#redis-metrics)
+- [Numbers metric](#numbers-metrics)
 - [Generic metric](#generic-metrics)
 
 1. Determine the location of instrumentation class: either under `ee` or outside `ee`.