gitlab-org--gitlab-foss/doc/development/usage_ping/metrics_dictionary.md

stage	group	info
Growth	Product Intelligence	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 Dictionary Guide

This guide describes Metrics Dictionary and how it's implemented

Metrics Definition and validation

We are using JSON Schema to validate the metrics definition.

This process is meant to ensure consistent and valid metrics defined for Usage Ping. All metrics must:

• Comply with the defined JSON schema.
• Have a unique key_path .
• Have an owner.

All metrics are stored in YAML files:

• config/metrics

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 Usage Ping payload.
description	yes
product_section	yes	The section.
product_stage	no	The stage for the metric.
product_group	yes	The group that owns the metric.
product_category	no	The product category for the metric.
value_type	yes	string; one of string, number, boolean, object.
status	yes	string; status of the metric, may be set to data_available, implemented, not_used, deprecated.
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.
distribution	yes	array; may be set to one of ce, ee or ee. The distribution where the tracked feature is available.
tier	yes	array; may be set to one of free, premium, ultimate, premium, ultimate or ultimate. The tier where the tracked feature is available.
milestone	no	The milestone when the metric is introduced.
milestone_removed	no	The milestone when the metric is removed.
introduced_by_url	no	The URL to the Merge Request that introduced the metric.
skip_validation	no	This should not be set. Used for imported metrics until we review, update and make them valid.

Metric statuses

Metric definitions can have one of the following statuses:

• data_available: Metric data is available and used in a Sisense dashboard.
• implemented: Metric is implemented but data is not yet available. This is a temporary status for newly added metrics awaiting inclusion in a new release.
• not_used: Metric is not used in any dashboard.
• deprecated: Metric is deprecated and possibly planned to be removed.

Example YAML metric definition

The linked uuid YAML file includes an example metric definition, where the uuid metric is the GitLab instance unique identifier.

key_path: uuid
description: GitLab instance unique identifier
product_category: collection
product_section: growth
product_stage: growth
product_group: group::product intelligence
value_type: string
status: data_available
milestone: 9.1
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521
time_frame: none
data_source: database
distribution:
- ce
- ee
tier:
- free
- premium
- ultimate

Create a new metric definition

The GitLab codebase provides a dedicated generator to create new metric definitions.

For uniqueness, the generated file includes a timestamp prefix, in ISO 8601 format.

The generator takes the key path argument and 2 options and creates the metric YAML definition in corresponding location:

• --ee, --no-ee Indicates if metric is for EE.
• --dir=DIR indicates the metric directory. It must be one of: counts_7d, 7d, counts_28d, 28d, counts_all, all, settings, license.

bundle exec rails generate gitlab:usage_metric_definition counts.issues --dir=7d
create  config/metrics/counts_7d/issues.yml

NOTE: To create a metric definition used in EE, add the --ee flag.

bundle exec rails generate gitlab:usage_metric_definition counts.issues --ee --dir=7d
create  ee/config/metrics/counts_7d/issues.yml

Metrics added dynamic to Usage Ping payload

The Redis HLL metrics are added automatically to Usage Ping payload.

A YAML metric definition is required for each metric. A dedicated generator is provided to create metric definitions for Redis HLL events.

The generator takes category and event arguments, as the root key will be redis_hll_counters, and creates two metric definitions for weekly and monthly timeframes:

bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues i_closed
create  config/metrics/counts_7d/i_closed_weekly.yml
create  config/metrics/counts_28d/i_closed_monthly.yml