diff options
Diffstat (limited to 'doc/development/service_ping/metrics_instrumentation.md')
-rw-r--r-- | doc/development/service_ping/metrics_instrumentation.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md new file mode 100644 index 00000000000..61a1ff828be --- /dev/null +++ b/doc/development/service_ping/metrics_instrumentation.md @@ -0,0 +1,102 @@ +--- +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 Service 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 Service Ping metric. + +- **Metric definition** + The Service 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 Service 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/61685). + +Count unique values for `i_quickactions_approve` event. + +```yaml +time_frame: 28d +data_source: redis_hll +instrumentation_class: 'Gitlab::Usage::Metrics::Instrumentations::RedisHLLMetric' +options: + events: + - i_quickactions_approve +``` + +## 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 +``` + +## Creating a new metric instrumentation class + +To create a stub instrumentation for a Service Ping metric, you can use a dedicated [generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_generator.rb): + +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_hll`. +- `--ee` Indicates if the metric is for EE. + +```shell +rails generate gitlab:usage_metric CountIssues --type database + create lib/gitlab/usage/metrics/instrumentations/count_issues_metric.rb + create spec/lib/gitlab/usage/metrics/instrumentations/count_issues_metric_spec.rb +``` |