Merge branch 'ce-62234-custom-metrics-help-text' into 'master'

Clarify requirements for custom metrics in docs

See merge request gitlab-org/gitlab-ce!31286

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)