Merge branch 'docs-aqualls-gitlab-metrics' into 'master'

Docs: tone and style, GitLab metrics page

See merge request gitlab-org/gitlab!33889

doc/.vale/gitlab/Acronyms.yml

@@ -40,6 +40,7 @@ exceptions:
   - POST
   - PUT
   - RSA
+  - RSS
   - SAML
   - SCP
   - SCSS
@@ -51,6 +52,7 @@ exceptions:
   - TIP
   - TLS
   - TODO
+  - UNIX
   - URI
   - URL
   - VPC

doc/.vale/gitlab/spelling-exceptions.txt

@@ -113,6 +113,7 @@ Dreamweaver
 Elasticsearch
 enablement
 enqueued
+ETag
 Excon
 expirable
 Facebook

doc/administration/monitoring/prometheus/gitlab_metrics.md

@@ -6,30 +6,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # GitLab Prometheus metrics
 
->**Note:**
-Available since [Omnibus GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29118). For
-installations from source you'll have to configure it yourself.
-
 To enable the GitLab Prometheus metrics:
 
-1. Log into GitLab as an administrator.
-1. Navigate to **Admin Area > Settings > Metrics and profiling**.
+1. Log into GitLab as a user with [administrator permissions](../../../user/permissions.md).
+1. Navigate to **{admin}** **Admin Area > Settings > Metrics and profiling**.
 1. Find the **Metrics - Prometheus** section, and click **Enable Prometheus Metrics**.
 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect.
 
+NOTE: **Note:**
+For installations from source you'll have to configure it yourself.
+
 ## Collecting the metrics
 
 GitLab monitors its own internal service metrics, and makes them available at the
-`/-/metrics` endpoint. Unlike other [Prometheus](https://prometheus.io) exporters, in order to access
-it, the client IP needs to be [included in a whitelist](../ip_whitelist.md).
+`/-/metrics` endpoint. Unlike other [Prometheus](https://prometheus.io) exporters, to access
+it, the client IP address needs to be [explicitly allowed](../ip_whitelist.md).
 
-For Omnibus and Chart installations, these metrics are automatically enabled
-and collected as of [GitLab
-9.4](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1702). For
-source installations or earlier versions, these metrics will need to be enabled
+For [Omnibus GitLab](https://docs.gitlab.com/omnibus/) and Chart installations,
+these metrics are enabled and collected as of
+[GitLab 9.4](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1702).
+For source installations or earlier versions, these metrics must be enabled
 manually and collected by a Prometheus server.
 
-See also [Sidekiq metrics](#sidekiq-metrics) for how to enable and view metrics from Sidekiq nodes.
+For enabling and viewing metrics from Sidekiq nodes, see [Sidekiq metrics](#sidekiq-metrics).
 
 ## Metrics available
 
@@ -50,7 +49,7 @@ The following metrics are available:
 | `gitlab_method_call_duration_seconds`                          | Histogram |                   10.2 | Method calls real duration                                                                          | `controller`, `action`, `module`, `method`          |
 | `gitlab_page_out_of_bounds`                                    | Counter   |                   12.8 | Counter for the PageLimiter pagination limit being hit                                              | `controller`, `action`, `bot`                       |
 | `gitlab_rails_queue_duration_seconds`                          | Histogram |                    9.4 | Measures latency between GitLab Workhorse forwarding a request to Rails                             |                                                     |
-| `gitlab_sql_duration_seconds`                                  | Histogram |                   10.2 | SQL execution time, excluding SCHEMA operations and BEGIN / COMMIT                                  |                                                     |
+| `gitlab_sql_duration_seconds`                                  | Histogram |                   10.2 | SQL execution time, excluding `SCHEMA` operations and `BEGIN` / `COMMIT`                                  |                                                     |
 | `gitlab_transaction_allocated_memory_bytes`                    | Histogram |                   10.2 | Allocated memory for all transactions (`gitlab_transaction_*` metrics)                                |                                                     |
 | `gitlab_transaction_cache_<key>_count_total`                   | Counter   |                   10.2 | Counter for total Rails cache calls (per key)                                                       |                                                     |
 | `gitlab_transaction_cache_<key>_duration_total`                | Counter   |                   10.2 | Counter for total time (seconds) spent in Rails cache calls (per key)                               |                                                     |
@@ -65,11 +64,11 @@ The following metrics are available:
 | `gitlab_transaction_event_build_not_found_total`               | Counter   |                    9.4 | Counter for build not found for API /jobs/request                                                   |                                                     |
 | `gitlab_transaction_event_change_default_branch_total`         | Counter   |                    9.4 | Counter when default branch is changed for any repository                                           |                                                     |
 | `gitlab_transaction_event_create_repository_total`             | Counter   |                    9.4 | Counter when any repository is created                                                              |                                                     |
-| `gitlab_transaction_event_etag_caching_cache_hit_total`        | Counter   |                    9.4 | Counter for etag cache hit.                                                                         | `endpoint`                                          |
-| `gitlab_transaction_event_etag_caching_header_missing_total`   | Counter   |                    9.4 | Counter for etag cache miss - header missing                                                        | `endpoint`                                          |
-| `gitlab_transaction_event_etag_caching_key_not_found_total`    | Counter   |                    9.4 | Counter for etag cache miss - key not found                                                         | `endpoint`                                          |
-| `gitlab_transaction_event_etag_caching_middleware_used_total`  | Counter   |                    9.4 | Counter for etag middleware accessed                                                                | `endpoint`                                          |
-| `gitlab_transaction_event_etag_caching_resource_changed_total` | Counter   |                    9.4 | Counter for etag cache miss - resource changed                                                      | `endpoint`                                          |
+| `gitlab_transaction_event_etag_caching_cache_hit_total`        | Counter   |                    9.4 | Counter for ETag cache hit.                                                                         | `endpoint`                                          |
+| `gitlab_transaction_event_etag_caching_header_missing_total`   | Counter   |                    9.4 | Counter for ETag cache miss - header missing                                                        | `endpoint`                                          |
+| `gitlab_transaction_event_etag_caching_key_not_found_total`    | Counter   |                    9.4 | Counter for ETag cache miss - key not found                                                         | `endpoint`                                          |
+| `gitlab_transaction_event_etag_caching_middleware_used_total`  | Counter   |                    9.4 | Counter for ETag middleware accessed                                                                | `endpoint`                                          |
+| `gitlab_transaction_event_etag_caching_resource_changed_total` | Counter   |                    9.4 | Counter for ETag cache miss - resource changed                                                      | `endpoint`                                          |
 | `gitlab_transaction_event_fork_repository_total`               | Counter   |                    9.4 | Counter for repository forks (RepositoryForkWorker). Only incremented when source repository exists |                                                     |
 | `gitlab_transaction_event_import_repository_total`             | Counter   |                    9.4 | Counter for repository imports (RepositoryImportWorker)                                             |                                                     |
 | `gitlab_transaction_event_push_branch_total`                   | Counter   |                    9.4 | Counter for all branch pushes                                                                       |                                                     |
@@ -239,7 +238,7 @@ Unicorn specific metrics, when Unicorn is used.
 When Puma is used instead of Unicorn, the following metrics are available:
 
 | Metric                            | Type    | Since | Description |
-|:---------------------------------------------- |:------- |:----- |:----------- |
+|:--------------------------------- |:------- |:----- |:----------- |
 | `puma_workers`                    | Gauge   | 12.0  | Total number of workers |
 | `puma_running_workers`            | Gauge   | 12.0  | Number of booted workers |
 | `puma_stale_workers`              | Gauge   | 12.0  | Number of old workers |
@@ -255,14 +254,11 @@ When Puma is used instead of Unicorn, the following metrics are available:
 
 GitLab's Prometheus client requires a directory to store metrics data shared between multi-process services.
 Those files are shared among all instances running under Unicorn server.
-The directory needs to be accessible to all running Unicorn's processes otherwise
-metrics will not function correctly.
-
-For best performance its advisable that this directory will be located in `tmpfs`.
-
-Its location is configured using environment variable `prometheus_multiproc_dir`.
+The directory must be accessible to all running Unicorn's processes, or
+metrics won't function correctly.
 
-If GitLab is installed using Omnibus and `tmpfs` is available then metrics
-directory will be automatically configured.
+This directory's location is configured using environment variable `prometheus_multiproc_dir`.
+For best performance, create this directory in `tmpfs`.
 
-[← Back to the main Prometheus page](index.md)
+If GitLab is installed using [Omnibus GitLab](https://docs.gitlab.com/omnibus/)
+and `tmpfs` is available, then the metrics directory will be configured for you.