Merge branch 'mc/docs/ci-templates-metrics' into 'master'

Document CI template metric definition requirement

See merge request gitlab-org/gitlab!78403

doc/development/cicd/templates.md

@@ -18,6 +18,7 @@ Before submitting a merge request with a new or updated CI/CD template, you must
 - Name the template following the `*.gitlab-ci.yml` format.
 - Use valid [`.gitlab-ci.yml` syntax](../../ci/yaml/index.md). Verify it's valid
   with the [CI/CD lint tool](../../ci/lint.md).
+- [Add template metrics](#add-metrics).
 - Include [a changelog](../changelog.md) if the merge request introduces a user-facing change.
 - Follow the [template review process](#contribute-cicd-template-merge-requests).
 - (Optional but highly recommended) Test the template in an example GitLab project
@@ -382,6 +383,77 @@ you must:
 This information is important for users when [a stable template](#stable-version)
 is updated in a major version GitLab release.
 
+### Add metrics
+
+Every CI/CD template must also have metrics defined to track their use.
+
+To add a metric definition for a new template:
+
+1. Install and start the [GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit#installation).
+1. In the `gitlab` directory in your GDK, check out the branch that contains the new template.
+1. [Add the template inclusion event](../service_ping/implement.md#add-new-events)
+   with this Rake task:
+
+   ```shell
+   bin/rake gitlab:usage_data:generate_ci_template_events
+   ```
+
+   The task adds a section like the following to [`lib/gitlab/usage_data_counters/known_events/ci_templates.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/ci_templates.yml):
+
+   ```yaml
+   - name: p_ci_templates_my_template_name
+     category: ci_templates
+     redis_slot: ci_templates
+     aggregation: weekly
+   ```
+
+1. Copy the value of `name` from the new YAML section, and add it to the weekly
+   and monthly CI/CD template total count metrics:
+   - [`config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml)
+   - [`config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml)
+
+1. Use the same `name` as above as the last argument in the following command to
+  [add new metric definitions](../service_ping/metrics_dictionary.md#metrics-added-dynamic-to-service-ping-payload):
+
+   ```shell
+   bundle exec rails generate gitlab:usage_metric_definition:redis_hll ci_templates <template_metric_event_name>
+   ```
+
+   The output should look like:
+
+   ```shell
+   $ bundle exec rails generate gitlab:usage_metric_definition:redis_hll ci_templates p_ci_templates_my_template_name
+         create  config/metrics/counts_7d/20220120073740_p_ci_templates_my_template_name_weekly.yml
+         create  config/metrics/counts_28d/20220120073746_p_ci_templates_my_template_name_monthly.yml
+   ```
+
+1. Edit both newly generated files as follows:
+
+   - `name:` and `performance_indicator_type:`: Delete (not needed).
+   - `introduced_by_url:`: The URL of the MR adding the template.
+   - `data_source:`: Set to `redis_hll`.
+   - All other fields that have no values: Set to empty strings (`''`).
+   - Add the following to the end of each file:
+
+     ```yaml
+     options:
+       events:
+         - p_ci_templates_my_template_name
+     ```
+
+1. Commit and push the changes.
+
+For example, these are the metrics configuration files for the
+[5 Minute Production App template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/5-Minute-Production-App.gitlab-ci.yml):
+
+- The template inclusion event: [`lib/gitlab/usage_data_counters/known_events/ci_templates.yml#L438-L441`](https://gitlab.com/gitlab-org/gitlab/-/blob/dcddbf83c29d1ad0839d55362c1b43888304f453/lib/gitlab/usage_data_counters/known_events/ci_templates.yml#L438-L441)
+- The weekly and monthly metrics definitions:
+  - [`config/metrics/counts_7d/20210901223501_p_ci_templates_5_minute_production_app_weekly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/1a6eceff3914f240864b2ca15ae2dc076ea67bf6/config/metrics/counts_7d/20210216184515_p_ci_templates_5_min_production_app_weekly.yml)
+  - [`config/metrics/counts_28d/20210901223505_p_ci_templates_5_minute_production_app_monthly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184517_p_ci_templates_5_min_production_app_monthly.yml)
+- The metrics count totals:
+  - [`config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml#L19`](https://gitlab.com/gitlab-org/gitlab/-/blob/4e01ef2b094763943348655ef77008aba7a052ae/config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml#L19)
+  - [`config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml#L19`](https://gitlab.com/gitlab-org/gitlab/-/blob/4e01ef2b094763943348655ef77008aba7a052ae/config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml#L19)
+
 ## Security
 
 A template could contain malicious code. For example, a template that contains the `export` shell command in a job