SONAR-15767 document /api/monitoring/metrics endpoint

diff --git a/server/sonar-docs/src/pages/setup/sonarqube-cluster-on-kubernetes.md b/server/sonar-docs/src/pages/setup/sonarqube-cluster-on-kubernetes.md
index 6dfa809e7e7144ee32e2a88267990366fe607ca0..1664fb227810eb4b3c26f40128c6681eb3fdec9c 100644 (file)
--- a/server/sonar-docs/src/pages/setup/sonarqube-cluster-on-kubernetes.md
+++ b/server/sonar-docs/src/pages/setup/sonarqube-cluster-on-kubernetes.md
@@ -86,7 +86,19 @@ ingress:
 
 ### Monitoring
 
-Currently, no cloud-native monitoring solutions play nicely with SonarQube or are supported by SonarSource. It is, however, possible to expose at least the JMX metrics to Prometheus with the help of the Prometheus JMX exporter for the Application Nodes.
+You can monitor your SonarQube cluster using SonarQube's native integration with Prometheus. Through this integration, you can ensure your cluster is running properly and know if you need to take action to prevent future issues. 
+
+Prometheus monitors your SonarQube cluster by collecting metrics from the `/api/monitoring/metrics` endpoint. Results are returned in OpenMetrics text format. See Prometheus' documentation on [Exposition Formats](https://prometheus.io/docs/instrumenting/exposition_formats/) for more information on the OpenMetrics text format. 
+
+Monitoring through this endpoint requires authentication. You can access the endpoint following ways:
+
+- **`Authorization:Bearer xxxx` header:** You can use a bearer token during database upgrade and when SonarQube is fully operational. Define the bearer token in the `sonar.properties` file using the `sonar.web.systemPasscode property`.
+- **`X-Sonar-Passcode: xxxxx` header:** You can use `X-Sonar-passcode` during database upgrade and when SonarQube is fully operational. Define `X-Sonar-passcode` in the `sonar.properties` file using the `sonar.web.systemPasscode property`.
+- **username:password and JWT token:** When SonarQube is fully operational, system admins logged in with local or delegated authentication can access the endpoint. 
+
+####**JMX Exporter**
+You can also expose at the JMX metrics to Prometheus with the help of the Prometheus JMX exporter.
+
 To use this option, set the following values in your `values.yaml` file:
 
 ```yaml
@@ -99,9 +111,9 @@ prometheusExporter:
 
 This downloads the Prometheus JMX exporter agent and adds it to the startup options of SonarQube. With this default configuration, the JMX metrics will be exposed on /metrics for Prometheus to scrape.
 
-The config scope here defines a configuration that is understandable by the Prometheus JMX exporter. For more information, please see the [documentation](https://github.com/prometheus/jmx_exporter).
+The config scope here defines a configuration that is understandable by the Prometheus JMX exporter. For more information, please Prometheus' documentation on the [JMX Exporter](https://github.com/prometheus/jmx_exporter).
 
-#### PodMonitor
+#### **PodMonitor**
 
 You can collect metrics on application nodes using PodMonitor for Prometheus. Search node monitoring is not currently supported. To monitor applications nodes, define PodMonitor as follows:
 

diff --git a/server/sonar-docs/src/pages/setup/sonarqube-on-kubernetes.md b/server/sonar-docs/src/pages/setup/sonarqube-on-kubernetes.md
index 63e1b5d695d03708fdd99aacbca6e4edc9fd4179..87b0f1ed293b45cfe720d0f5ca81a20cccf805d8 100644 (file)
--- a/server/sonar-docs/src/pages/setup/sonarqube-on-kubernetes.md
+++ b/server/sonar-docs/src/pages/setup/sonarqube-on-kubernetes.md
@@ -207,8 +207,19 @@ ingress:
 ```
 
 ### Monitoring
+You can monitor your SonarQube instance using SonarQube's native integration with Prometheus. Through this integration, you can ensure your instance is running properly and know if you need to take action to prevent future issues. 
+
+Prometheus monitors your SonarQube instance by collecting metrics from the `/api/monitoring/metrics` endpoint. Results are returned in OpenMetrics text format. See Prometheus' documentation on [Exposition Formats](https://prometheus.io/docs/instrumenting/exposition_formats/) for more information on the OpenMetrics text format. 
+
+Monitoring through this endpoint requires authentication. You can access the endpoint following ways:
+
+- **`Authorization:Bearer xxxx` header:** You can use a bearer token during database upgrade and when SonarQube is fully operational. Define the bearer token in the `sonar.properties` file using the `sonar.web.systemPasscode property`.
+- **`X-Sonar-Passcode: xxxxx` header:** You can use `X-Sonar-passcode` during database upgrade and when SonarQube is fully operational. Define `X-Sonar-passcode` in the `sonar.properties` file using the `sonar.web.systemPasscode property`.
+- **username:password and JWT token:** When SonarQube is fully operational, system admins logged in with local or delegated authentication can access the endpoint. 
+
+####**JMX Exporter**
+You can also expose the JMX metrics to Prometheus using the Prometheus JMX exporter.
 
-Currently, no cloud-native monitoring solutions play nicely with SonarQube or are supported by SonarSource. It is, however, possible to expose at least the JMX metrics to Prometheus with the help of the Prometheus JMX exporter for the Application Nodes.
 To use this option, set the following values in your `values.yaml` file:
 
 ```yaml
@@ -221,11 +232,11 @@ prometheusExporter:
 
 This downloads the Prometheus JMX exporter agent and adds it to the startup options of SonarQube. With this default configuration, the JMX metrics will be exposed on /metrics for Prometheus to scrape.
 
-The config scope here defines a configuration that is understandable by the Prometheus JMX exporter. For more information, please see the [documentation](https://github.com/prometheus/jmx_exporter).
+The config scope here defines a configuration that is understandable by the Prometheus JMX exporter. For more information, please Prometheus' documentation on the [JMX Exporter](https://github.com/prometheus/jmx_exporter).
 
-#### PodMonitor
+#### **PodMonitor**
 
-You can collect metrics on application nodes using PodMonitor for Prometheus. Search node monitoring is not currently supported. To monitor applications nodes, define PodMonitor as follows:
+You can collect metrics on using PodMonitor for Prometheus by defining PodMonitor as follows:
 
 ```yaml
 apiVersion: monitoring.coreos.com/v1