Add broken status to Product Intelligence metrics

config/metrics/schema.json

@@ -30,7 +30,7 @@
     },
     "status": {
       "type": ["string"],
-      "enum": ["data_available", "implemented", "not_used", "deprecated", "removed"]
+      "enum": ["data_available", "implemented", "not_used", "deprecated", "removed", "broken"]
     },
     "milestone": {
       "type": ["string", "null"],
@@ -43,6 +43,9 @@
     "introduced_by_url": {
       "type": ["string", "null"]
     },
+    "repair_issue_url": {
+      "type": ["string"]
+    },
     "options": {
       "type": "object"
     },
@@ -78,5 +81,17 @@
     "value_json_schema": {
       "type": "string"
     }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": { "const": "broken" }
+        }
+      },
+      "then": {
+        "required": ["repair_issue_url"]
+      }
     }
+  ]
 }

doc/development/usage_ping/metrics_dictionary.md

@@ -34,7 +34,7 @@ Each metric is defined in a separate YAML file consisting of a number of fields:
 | `product_group`     | yes      | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the metric. |
 | `product_category`  | no       | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the metric. |
 | `value_type`        | yes      | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html).                                                     |
-| `status`            | yes      | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`. |
+| `status`            | yes      | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`, `broken`. |
 | `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`, `system`. |
 | `instrumentation_class` | no   | `string`; [the class that implements the metric](metrics_instrumentation.md).  |
@@ -43,6 +43,7 @@ Each metric is defined in a separate YAML file consisting of a number of fields:
 | `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. |
+| `repair_issue_url`  | no       | The URL of the issue that was created to repair a metric with a `broken` status. |
 | `options`           | no       | `object`: options information needed to calculate the metric value. |
 | `skip_validation`   | no       | This should **not** be set. [Used for imported metrics until we review, update and make them valid](https://gitlab.com/groups/gitlab-org/-/epics/5425). |
 
@@ -53,6 +54,7 @@ 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.
+- `broken`: Metric reports broken data (for example, -1 fallback), or does not report data at all. A metric marked as `broken` must also have the `repair_issue_url` attribute.
 - `not_used`: Metric is not used in any dashboard.
 - `deprecated`: Metric is deprecated and possibly planned to be removed.
 - `removed`: Metric was removed, but it may appear in Usage Ping payloads sent from instances running on older versions of GitLab.

spec/lib/gitlab/usage/metric_definition_spec.rb

@@ -73,6 +73,7 @@ RSpec.describe Gitlab::Usage::MetricDefinition do
       :distribution       | 'test'
       :tier               | %w(test ee)
       :name               | 'count_<adjective_describing>_boards'
+      :repair_issue_url   | nil
 
       :instrumentation_class | 'Metric_Class'
       :instrumentation_class | 'metricClass'
@@ -103,6 +104,19 @@ RSpec.describe Gitlab::Usage::MetricDefinition do
         end
       end
     end
+
+    context 'conditional validations' do
+      context 'when metric has broken status' do
+        it 'has to have repair issue url provided' do
+          attributes[:status] = 'broken'
+          attributes.delete(:repair_issue_url)
+
+          expect(Gitlab::ErrorTracking).to receive(:track_and_raise_for_dev_exception).at_least(:once).with(instance_of(Gitlab::Usage::Metric::InvalidMetricError))
+
+          described_class.new(path, attributes).validate!
+        end
+      end
+    end
   end
 
   describe 'statuses' do
@@ -153,7 +167,7 @@ RSpec.describe Gitlab::Usage::MetricDefinition do
       is_expected.to be_one
     end
 
-    it 'when the same meric is defined multiple times raises exception' do
+    it 'when the same metric is defined multiple times raises exception' do
       write_metric(metric1, path, yaml_content)
       write_metric(metric2, path, yaml_content)