kotovalexarian-likes-gitlab
/
gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/development/usage_ping/metrics_dictionary.md

6.2 KiB
Raw Blame History

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:

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