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
value_type	yes
status	yes
product_group	yes	The group that owns the metric.
time_frame	yes	string; may be set to a value like "7d"
data_source	yes	string: may be set to a value like database or redis_hll.
distribution	yes	The distribution where the metric applies.
tier	yes	The tier where the metric applies.
product_category	no	The product category for the metric.
product_stage	no	The stage for the metric.
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.

Example 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
value_type: string
product_category: collection
product_stage: growth
status: data_available
milestone: 9.1
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521
product_group: group::product intelligence
time_frame: none
data_source: database
distribution: [ee, ce]
tier: ['free', 'starter', 'premium', 'ultimate', 'bronze', 'silver', 'gold']

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