Add help text next to Custom Metrics section

- Also add requirements to the docs for custom metrics.

3 files changed, 38 insertions, 32 deletions

diff --git a/app/views/projects/services/prometheus/_metrics.html.haml b/app/views/projects/services/prometheus/_metrics.html.haml
index a1d74b91002..3aefb3fdbb9 100644
--- a/app/views/projects/services/prometheus/_metrics.html.haml
+++ b/app/views/projects/services/prometheus/_metrics.html.haml
@@ -1,28 +1,34 @@
 - 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
diff --git a/app/views/projects/services/prometheus/_show.html.haml b/app/views/projects/services/prometheus/_show.html.haml
index 6aafa85e99a..c719661d8e8 100644
--- a/app/views/projects/services/prometheus/_show.html.haml
+++ b/app/views/projects/services/prometheus/_show.html.haml
@@ -1,12 +1,9 @@
-.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
diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md
index e609fe43507..44439b59e77 100644
--- a/doc/user/project/integrations/prometheus.md
+++ b/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)