Merge branch '326449-update-docs-for-metrics-definition-and-instrumentation-class' into 'master'

Update docs for metrics definition and instrumentation class

See merge request gitlab-org/gitlab!61243

doc/development/usage_ping/metrics_dictionary.md

@@ -37,6 +37,7 @@ Each metric is defined in a separate YAML file consisting of a number of fields:
 | `status`            | yes      | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`. |
 | `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`, `ruby`. |
+| `instrumentation_class` | no   | `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.  |
 | `tier`              | yes      | `array`; may be set to one of `free, premium, ultimate`, `premium, ultimate` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. |
 | `milestone`         | no       | The milestone when the metric is introduced. |

doc/development/usage_ping/metrics_instrumentation.md

+---
+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
+---
+
+# Metrics instrumentation guide
+
+This guide describes how to develop Usage Ping metrics using metrics instrumentation.
+
+## Nomenclature
+
+- **Instrumentation class**:
+  - Inherits one of the metric classes: `DatabaseMetric`, `RedisHLLMetric` or `GenericMetric`.
+  - Implements the logic that calculates the value for a Usage Ping metric.
+
+- **Metric definition**
+  The Usage Data metric YAML definition.
+
+- **Hardening**:
+  Hardening a method is the process that ensures the method fails safe, returning a fallback value like -1.
+
+## How it works
+
+A metric definition has the [`instrumentation_class`](metrics_dictionary.md) field, which can be set to a class.
+
+The defined instrumentation class should have one of the existing metric classes: `DatabaseMetric`, `RedisHLLMetric`, or `GenericMetric`.
+
+Using the instrumentation classes ensures that metrics can fail safe individually, without breaking the entire 
+ process of Usage Ping generation.
+
+We have built a domain-specific language (DSL) to define the metrics instrumentation.
+
+## Database metrics
+
+[Example of a merge request that adds a database metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60022).
+
+```ruby
+module Gitlab
+  module Usage
+    module Metrics
+      module Instrumentations
+        class CountBoardsMetric < DatabaseMetric
+          operation :count
+
+          relation { Board }
+        end
+      end
+    end
+  end
+end
+```
+
+## Redis HyperLogLog metrics
+
+[Example of a merge request that adds a `RedisHLL` metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60089/diffs).
+
+```ruby
+module Gitlab
+  module Usage
+    module Metrics
+      module Instrumentations
+        class CountUsersUsingApproveQuickActionMetric < RedisHLLMetric
+          event_names :i_quickactions_approve
+        end
+      end
+    end
+  end
+end
+```
+
+## Generic metrics
+
+[Example of a merge request that adds a generic metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60256).
+
+```ruby
+module Gitlab
+  module Usage
+    module Metrics
+      module Instrumentations
+        class UuidMetric < GenericMetric
+          value do
+            Gitlab::CurrentSettings.uuid
+          end
+        end
+      end
+    end
+  end
+end
+```