Merge branch 'docs-aqualls-revise-metrics-page' into 'master'

Begin revising metrics page for flow

See merge request gitlab-org/gitlab!38972

doc/operations/metrics/index.md

@@ -4,7 +4,64 @@ group: APM
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# Metrics dashboard for your CI/CD environment **(CORE)**
+# Monitor your CI/CD environment's metrics **(CORE)**
+
+GitLab helps your team monitor the health and performance of your applications
+and infrastructure by turning statistics and log files into charts and graphs
+that are easy to understand, especially when time is short and decisions are
+critical. For GitLab to display your information in charts, you must:
+
+1. **Instrument your application** - Collect accurate and complete measurements.
+   <I class="fa fa-youtube-play youtube" aria-hidden="true"></I>
+   For an overview, see [How to instrument Prometheus metrics in GitLab](https://www.youtube.com/watch?v=tuI2oJ3TTB4).
+1. **Expose metrics for capture** - Make logs, metrics, and traces available for capture.
+1. [**Configure Prometheus to gather metrics**](#configure-prometheus-to-gather-metrics) -
+   Deploy managed applications like Elasticsearch, Prometheus, and Jaeger to gather
+   the data you've exposed.
+1. **GitLab collects metrics** - GitLab uses Prometheus to scrape the data you've
+   captured in your managed apps, and prepares the data for display. To learn more, read
+   [Collect and process metrics](#collect-and-process-metrics).
+1. **Display charts in the GitLab user interface** - GitLab converts your metrics
+   into easy-to-read charts on a default dashboard. You can create as many custom charts
+   and custom dashboards as needed so your team has full insight into your
+   application's health.
+
+## Configure Prometheus to gather metrics
+
+You must connect a Prometheus instance to GitLab to collect metrics. How you configure
+your Prometheus integration depends on where your apps are running:
+
+- **For manually-configured Prometheus** -
+  [Specify your Prometheus server](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus),
+  and define at least one environment.
+- **For GitLab-managed Prometheus** - GitLab can
+  [deploy and manage Prometheus](../../user/project/integrations/prometheus.md#managed-prometheus-on-kubernetes) for you.
+  You must also complete a code deployment, as described in
+  [Deploy code with GitLab-managed Prometheus](#deploy-code-with-gitlab-managed-prometheus),
+  for the **Operations > Metrics** page to contain data.
+
+### Deploy code with GitLab-managed Prometheus
+
+For GitLab-managed Prometheus, you can set up [Auto DevOps](../../topics/autodevops/index.md)
+to quickly create a deployment:
+
+1. Navigate to your project's **Operations > Kubernetes** page.
+1. Ensure that, in addition to Prometheus, you also have Runner and Ingress
+   installed.
+1. After installing Ingress, copy its endpoint.
+1. Navigate to your project's **Settings > CI/CD** page. In the
+   **Auto DevOps** section, select a deployment strategy and save your changes.
+1. On the same page, in the **Variables** section, add a variable named
+   `KUBE_INGRESS_BASE_DOMAIN` with the value of the Ingress endpoint you
+   copied previously. Leave the type as **Variable**.
+1. Navigate to your project's **{rocket}** **CI/CD > Pipelines** page, and run a
+   pipeline on any branch.
+1. When the pipeline has run successfully, graphs are available on the
+   **Operations > Metrics** page.
+
+![Monitoring Dashboard](img/prometheus_monitoring_dashboard_v13_3.png)
+
+## Collect and process metrics
 
 After [configuring Prometheus for a cluster](../../user/project/integrations/prometheus.md),
 GitLab attempts to retrieve performance metrics for any [environment](../../ci/environments/index.md) with
@@ -16,7 +73,8 @@ the supported metrics and scan processes, see the
 [Prometheus Metrics Library documentation](../../user/project/integrations/prometheus_library/index.md).
 
 To view the metrics dashboard for an environment that has
-[completed at least one deployment](#populate-your-metrics-dashboard):
+To view the metrics dashboard for an environment that is
+[configured to gather metrics](#configure-prometheus-to-gather-metrics):
 
 1. *If the metrics dashboard is only visible to project members,* sign in to
    GitLab as a member of a project. Learn more about [metrics dashboard visibility](#metrics-dashboard-visibility).
@@ -53,29 +111,6 @@ navigation bar contains:
 - **Metrics settings** - Configure the
   [settings for this dashboard](dashboards/index.md#manage-the-metrics-dashboard-settings).
 
-## Populate your metrics dashboard
-
-After [configuring Prometheus for a cluster](../../user/project/integrations/prometheus.md),
-you must also deploy code for the **Operations > Metrics** page
-to contain data. Setting up [Auto DevOps](../../topics/autodevops/index.md)
-helps quickly create a deployment:
-
-1. Navigate to your project's **Operations > Kubernetes** page.
-1. Ensure that, in addition to Prometheus, you also have Runner and Ingress
-   installed.
-1. After installing Ingress, copy its endpoint.
-1. Navigate to your project's **Settings > CI/CD** page. In the
-   **Auto DevOps** section, select a deployment strategy and save your changes.
-1. On the same page, in the **Variables** section, add a variable named
-   `KUBE_INGRESS_BASE_DOMAIN` with the value of the Ingress endpoint you
-   copied previously. Leave the type as **Variable**.
-1. Navigate to your project's **{rocket}** **CI/CD > Pipelines** page, and run a
-   pipeline on any branch.
-1. When the pipeline has run successfully, graphs are available on the
-   **Operations > Metrics** page.
-
-![Monitoring Dashboard](img/prometheus_monitoring_dashboard_v13_3.png)
-
 ## Customize your metrics dashboard
 
 After creating your dashboard, you can customize it to meet your needs: