diff options
Diffstat (limited to 'doc/development/usage_ping')
| -rw-r--r-- | doc/development/usage_ping/dictionary.md | 158 | ||||
| -rw-r--r-- | doc/development/usage_ping/metrics_dictionary.md | 41 |
2 files changed, 185 insertions, 14 deletions
diff --git a/doc/development/usage_ping/dictionary.md b/doc/development/usage_ping/dictionary.md new file mode 100644 index 00000000000..27a3ac42af6 --- /dev/null +++ b/doc/development/usage_ping/dictionary.md @@ -0,0 +1,158 @@ +--- +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/#designated-technical-writers +--- + +<!--- + This documentation is auto generated by a script. + + Please do not edit this file directly, check generate_metrics_dictionary task on lib/tasks/gitlab/usage_data.rake. +---> + +<!-- vale gitlab.Spelling = NO --> + +# Metrics Dictionary + +This file is autogenerated, please do not edit directly. + +To generate these files from the GitLab repository, run: + +```shell +bundle exec rake gitlab:usage_data:generate_metrics_dictionary +``` + +The Metrics Dictionary is based on the following metrics definition YAML files: + +- [`config/metrics`]('https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics') +- [`ee/config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/metrics) +Each table includes a `milestone`, which corresponds to the GitLab version when the metric +was released. + +## counts.deployments + +Total deployments count + +| field | value | +| --- | --- | +| `key_path` | **counts.deployments** | +| `value_type` | integer | +| `stage` | release | +| `status` | data_available | +| `milestone` | 8.12 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/735) | +| `group` | `group::ops release` | +| `time_frame` | all | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## counts.geo_nodes + +Total number of sites in a Geo deployment + +| field | value | +| --- | --- | +| `key_path` | **counts.geo_nodes** | +| `value_type` | integer | +| `product_category` | disaster_recovery | +| `stage` | enablement | +| `status` | data_available | +| `milestone` | 11.2 | +| `group` | `group::geo` | +| `time_frame` | all | +| `data_source` | Database | +| `distribution` | ee | +| `tier` | premium, ultimate | + +## counts_monthly.deployments + +Total deployments count for recent 28 days + +| field | value | +| --- | --- | +| `key_path` | **counts_monthly.deployments** | +| `value_type` | integer | +| `stage` | release | +| `status` | data_available | +| `milestone` | 13.2 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35493) | +| `group` | `group::ops release` | +| `time_frame` | 28d | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## database.adapter + +This metric only returns a value of PostgreSQL in supported versions of GitLab. It could be removed from the usage ping. Historically MySQL was also supported. + +| field | value | +| --- | --- | +| `key_path` | **database.adapter** | +| `value_type` | string | +| `product_category` | collection | +| `stage` | growth | +| `status` | data_available | +| `group` | `group::enablement distribution` | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## recorded_at + +When the Usage Ping computation was started + +| field | value | +| --- | --- | +| `key_path` | **recorded_at** | +| `value_type` | string | +| `product_category` | collection | +| `stage` | growth | +| `status` | data_available | +| `milestone` | 8.1 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/557) | +| `group` | `group::product analytics` | +| `time_frame` | none | +| `data_source` | Ruby | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## redis_hll_counters.issues_edit.g_project_management_issue_title_changed_weekly + +Distinct users count that changed issue title in a group for last recent week + +| field | value | +| --- | --- | +| `key_path` | **redis_hll_counters.issues_edit.g_project_management_issue_title_changed_weekly** | +| `value_type` | integer | +| `product_category` | issue_tracking | +| `stage` | plan | +| `status` | data_available | +| `milestone` | 13.6 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/issues/229918) | +| `group` | `group::project management` | +| `time_frame` | 7d | +| `data_source` | Redis_hll | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | + +## uuid + +GitLab instance unique identifier + +| field | value | +| --- | --- | +| `key_path` | **uuid** | +| `value_type` | string | +| `product_category` | collection | +| `stage` | growth | +| `status` | data_available | +| `milestone` | 9.1 | +| `introduced_by_url` | [Introduced by](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521) | +| `group` | `group::product analytics` | +| `time_frame` | none | +| `data_source` | Database | +| `distribution` | ee, ce | +| `tier` | free, starter, premium, ultimate, bronze, silver, gold | diff --git a/doc/development/usage_ping/metrics_dictionary.md b/doc/development/usage_ping/metrics_dictionary.md index bae79689f3b..7c41c331e88 100644 --- a/doc/development/usage_ping/metrics_dictionary.md +++ b/doc/development/usage_ping/metrics_dictionary.md @@ -14,24 +14,22 @@ We are using [JSON Schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/co This process is meant to ensure consistent and valid metrics defined for Usage Ping. All metrics *must*: -- Comply with the definied [JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/schema.json). -- Have a unique `full_path` . +- Comply with the defined [JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/schema.json). +- Have a unique `key_path` . - Have an owner. All metrics are stored in YAML files: - [`config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics) -Each metric is definied in a separate YAML file consisting of a number of fields: +Each metric is defined in a separate YAML file consisting of a number of fields: | Field | Required | Additional information | |---------------------|----------|----------------------------------------------------------------| -| `name` | yes | | +| `key_path` | yes | JSON key path for the metric, location in Usage Ping payload. | | `description` | yes | | | `value_type` | yes | | | `status` | yes | | -| `default_generation`| yes | Default generation path of the metric. One full_path value. (1) | -| `full_path` | yes | Full path of the metric for one or multiple generations. Path of the metric in Usage Ping payload. (1) | | `group` | yes | The [group](https://about.gitlab.com/handbook/product/categories/#devops-stages) 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`. | @@ -43,9 +41,6 @@ Each metric is definied in a separate YAML file consisting of a number of fields | `milestone_removed` | no | The milestone when the metric is removed. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the metric. | -1. The default generation path is the location of the metric in the Usage Ping payload. - The `full_path` is the list locations for multiple Usage Ping generaations. - ### Example metric definition The linked [`uuid`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/uuid.yml) @@ -53,16 +48,12 @@ YAML file includes an example metric definition, where the `uuid` metric is the instance unique identifier. ```yaml -name: uuid +key_path: uuid description: GitLab instance unique identifier value_type: string product_category: collection stage: growth status: data_available -default_generation: generation_1 -full_path: - generation_1: uuid - generation_2: license.uuid milestone: 9.1 introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521 group: group::product intelligence @@ -71,3 +62,25 @@ 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](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_definition_generator.rb) to create new metric definitions. + +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`. + +```shell +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. + +```shell +bundle exec rails generate gitlab:usage_metric_definition counts.issues --ee --dir=7d +create ee/config/metrics/counts_7d/issues.yml +``` |