Add help text next to Custom Metrics section

- Also add requirements to the docs for custom metrics.

app/views/projects/services/prometheus/_metrics.html.haml

 - project = local_assigns.fetch(:project)
 
-.card.js-panel-monitored-metrics{ data: { active_metrics: active_common_project_prometheus_metrics_path(project, :json), metrics_help_path: help_page_path('user/project/integrations/prometheus_library/index') } }
+.col-lg-3
+  %p
+    = s_('PrometheusService|Common metrics are automatically monitored based on a library of metrics from popular exporters.')
+    = link_to s_('PrometheusService|More information'), help_page_path('user/project/integrations/prometheus_library/index'), target: '_blank', rel: "noopener noreferrer"
+
+.col-lg-9
+  .card.js-panel-monitored-metrics{ data: { active_metrics: active_common_project_prometheus_metrics_path(project, :json), metrics_help_path: help_page_path('user/project/integrations/prometheus_library/index') } }
     .card-header
       = s_('PrometheusService|Common metrics')
       %span.badge.badge-pill.js-monitored-count 0
@@ -14,7 +20,7 @@
           = s_('PrometheusService|Waiting for your first deployment to an environment to find common metrics')
       %ul.list-unstyled.metrics-list.hidden.js-metrics-list
 
-.card.hidden.js-panel-missing-env-vars
+  .card.hidden.js-panel-missing-env-vars
     .card-header
       = icon('caret-right lg fw', class: 'panel-toggle js-panel-toggle', 'aria-label' => 'Toggle panel')
       = s_('PrometheusService|Missing environment variable')

app/views/projects/services/prometheus/_show.html.haml

-.row.prepend-top-default.append-bottom-default.prometheus-metrics-monitoring.js-prometheus-metrics-monitoring
+.row
   .col-lg-3
     %h4.prepend-top-0
       = s_('PrometheusService|Metrics')
-    %p
-      = s_('PrometheusService|Common metrics are automatically monitored based on a library of metrics from popular exporters.')
-      = link_to s_('PrometheusService|More information'), help_page_path('user/project/integrations/prometheus_library/index'), target: '_blank', rel: "noopener noreferrer"
 
-  .col-lg-9
+.row.append-bottom-default.prometheus-metrics-monitoring.js-prometheus-metrics-monitoring
   = render 'projects/services/prometheus/metrics', project: @project
 
 = render_if_exists 'projects/services/prometheus/external_alerts', project: @project

doc/user/project/integrations/prometheus.md

@@ -98,7 +98,10 @@ You can view the performance dashboard for an environment by [clicking on the mo
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6.
 
-Additional metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard.
+Custom metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard provided that either:
+
+- A [connected Kubernetes cluster](../clusters/index.md#adding-and-removing-clusters) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration), or
+- Prometheus is [manually configured](#manual-configuration-of-prometheus).
 
 ![Add New Metric](img/prometheus_add_metric.png)
 

ee/app/views/projects/services/prometheus/_metrics.html.haml

 - project = local_assigns.fetch(:project)
 
-.card.custom-monitored-metrics.js-panel-custom-monitored-metrics{ data: { active_custom_metrics: project_prometheus_metrics_path(project), environments_data: environments_list_data, service_active: "#{@service.active}" } }
+.col-lg-3
+  %p
+    = s_('PrometheusService|Custom metrics require Prometheus installed on a cluster with environment scope "*" OR a manually configured Prometheus to be available.')
+    = link_to s_('PrometheusService|More information'), help_page_path('user/project/integrations/prometheus', anchor: 'adding-additional-metrics-premium'), target: '_blank', rel: "noopener noreferrer"
+
+.col-lg-9
+  .card.custom-monitored-metrics.js-panel-custom-monitored-metrics{ data: { active_custom_metrics: project_prometheus_metrics_path(project), environments_data: environments_list_data, service_active: "#{@service.active}" } }
     .card-header
       %h3.card-title
         = s_('PrometheusService|Custom metrics')

ee/changelogs/unreleased/62234-custom-metrics-help-text.yml

+---
+title: Improve help text and docs about custom metrics
+merge_request: 14912
+author:
+type: fixed

locale/gitlab.pot

@@ -11489,6 +11489,9 @@ msgstr ""
 msgid "PrometheusService|Custom metrics"
 msgstr ""
 
+msgid "PrometheusService|Custom metrics require Prometheus installed on a cluster with environment scope \"*\" OR a manually configured Prometheus to be available."
+msgstr ""
+
 msgid "PrometheusService|Enable Prometheus to define custom metrics, using either option above"
 msgstr ""