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') } }
-  .card-header
-    = s_('PrometheusService|Common metrics')
-    %span.badge.badge-pill.js-monitored-count 0
-  .card-body
-    .loading-metrics.js-loading-metrics
-      %p.prepend-top-10.prepend-left-10
-        = icon('spinner spin', class: 'metrics-load-spinner')
-        = s_('PrometheusService|Finding and configuring metrics...')
-    .empty-metrics.hidden.js-empty-metrics
-      %p.text-tertiary.prepend-top-10.prepend-left-10
-        = s_('PrometheusService|Waiting for your first deployment to an environment to find common metrics')
-    %ul.list-unstyled.metrics-list.hidden.js-metrics-list
+.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"
 
-.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')
-    %span.badge.badge-pill.js-env-var-count 0
-  .card-body.hidden
-    .flash-container
-      .flash-notice
-        .flash-text
-          = s_("PrometheusService|To set up automatic monitoring, add the environment variable %{variable} to exporter's queries." % { variable: "<code>$CI_ENVIRONMENT_SLUG</code>" }).html_safe
-          = link_to s_('PrometheusService|More information'), help_page_path('user/project/integrations/prometheus', anchor: 'metrics-and-labels')
-    %ul.list-unstyled.metrics-list.js-missing-var-metrics-list
+.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
+    .card-body
+      .loading-metrics.js-loading-metrics
+        %p.prepend-top-10.prepend-left-10
+          = icon('spinner spin', class: 'metrics-load-spinner')
+          = s_('PrometheusService|Finding and configuring metrics...')
+      .empty-metrics.hidden.js-empty-metrics
+        %p.text-tertiary.prepend-top-10.prepend-left-10
+          = 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-header
+      = icon('caret-right lg fw', class: 'panel-toggle js-panel-toggle', 'aria-label' => 'Toggle panel')
+      = s_('PrometheusService|Missing environment variable')
+      %span.badge.badge-pill.js-env-var-count 0
+    .card-body.hidden
+      .flash-container
+        .flash-notice
+          .flash-text
+            = s_("PrometheusService|To set up automatic monitoring, add the environment variable %{variable} to exporter's queries." % { variable: "<code>$CI_ENVIRONMENT_SLUG</code>" }).html_safe
+            = link_to s_('PrometheusService|More information'), help_page_path('user/project/integrations/prometheus', anchor: 'metrics-and-labels')
+      %ul.list-unstyled.metrics-list.js-missing-var-metrics-list

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
-    = render 'projects/services/prometheus/metrics', project: @project
+.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}" } }
-  .card-header
-    %h3.card-title
-      = s_('PrometheusService|Custom metrics')
-      %span.badge.badge-pill.js-custom-monitored-count 0
-      = link_to s_('PrometheusService|New metric'), new_project_prometheus_metric_path(project), class: 'btn btn-success js-new-metric-button hidden'
-  .card-body
-    .flash-container.hidden
-      .flash-warning
-        .flash-text
-    .loading-metrics.js-loading-custom-metrics
-      %p.prepend-top-10.prepend-left-10
-        = icon('spinner spin', class: 'metrics-load-spinner')
-        = s_('PrometheusService|Finding custom metrics...')
-    .empty-metrics.hidden.js-empty-custom-metrics
-      %p.text-tertiary.prepend-top-10.prepend-left-10.js-no-active-integration-text.hidden
-        = s_('PrometheusService|Enable Prometheus to define custom metrics, using either option above')
-      = link_to s_('PrometheusService|New metric'), new_project_prometheus_metric_path(project), class: 'btn btn-success prepend-top-10 prepend-left-10 append-bottom-10 js-new-metric-body-button hidden'
-    %ul.list-unstyled.metrics-list.hidden.js-custom-metrics-list
+.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')
+        %span.badge.badge-pill.js-custom-monitored-count 0
+        = link_to s_('PrometheusService|New metric'), new_project_prometheus_metric_path(project), class: 'btn btn-success js-new-metric-button hidden'
+    .card-body
+      .flash-container.hidden
+        .flash-warning
+          .flash-text
+      .loading-metrics.js-loading-custom-metrics
+        %p.prepend-top-10.prepend-left-10
+          = icon('spinner spin', class: 'metrics-load-spinner')
+          = s_('PrometheusService|Finding custom metrics...')
+      .empty-metrics.hidden.js-empty-custom-metrics
+        %p.text-tertiary.prepend-top-10.prepend-left-10.js-no-active-integration-text.hidden
+          = s_('PrometheusService|Enable Prometheus to define custom metrics, using either option above')
+        = link_to s_('PrometheusService|New metric'), new_project_prometheus_metric_path(project), class: 'btn btn-success prepend-top-10 prepend-left-10 append-bottom-10 js-new-metric-body-button hidden'
+      %ul.list-unstyled.metrics-list.hidden.js-custom-metrics-list
 
 = render_ce 'projects/services/prometheus/metrics', project: project

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 ""